taaghche-mcp
Advanced tools
Unofficial read-only MCP server for Taaghche: search Persian ebooks and audiobooks, compare prices and formats, read reviews, browse bestsellers, new and free books.
Let your AI agent browse Taaghche (طاقچه), the Iranian ebook and audiobook store.
An unofficial, read-only MCP server for taaghche.com (about 220,000 Persian and translated titles):
search books, compare prices and formats, read reader reviews and catch bestsellers, new releases and free books,
from Claude, Cursor or Copilot. Prices in Toman, no API key, no account.
For AI agents · Quick start · What it can do · Tools · FAQ · فارسی
uvx taaghche-mcp or claude mcp add taaghche -- uvx taaghche-mcp. Transport: stdio. Needs uv (Python 3.10+).TAAGHCHE_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.tg_. Typical sequence: tg_search -> tg_book -> tg_reviews or tg_similar. For lists without words: tg_categories -> tg_browse, tg_bestsellers, tg_new_releases, tg_free_books.final_price is what the customer pays), rating 0-5, numeric book ids to pass between tools, paging with next_cursor.server.json and the iran-mcp catalog (TOOLS.md, servers.json, llms.txt).Taaghche is where many Iranian readers buy ebooks and audiobooks, but comparing editions, prices and reviews means
opening several pages. With taaghche-mcp an agent answers "is there an audiobook of this title, which edition is
cheapest, and what do readers say?" in a few calls and returns a short summary instead of page after page of listings.
You: Is there an audiobook of شازده کوچولو, and which edition is the cheapest?
Agent: calls
tg_search(query="شازده کوچولو", format="audiobook", sort="cheapest")->tg_book(book_id=...)It lists the matching audiobooks with price, discount, narrator and listening time, and points to the cheapest.
Example prompts:
You need uv. No API key or account.
claude mcp add taaghche -- uvx taaghche-mcp
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"taaghche": { "command": "uvx", "args": ["taaghche-mcp"] }
}
}
Add the Claude Desktop block above to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Click Install in VS Code above, or add to .vscode/mcp.json:
{
"servers": {
"taaghche": { "type": "stdio", "command": "uvx", "args": ["taaghche-mcp"] }
}
}
codex mcp add taaghche -- uvx taaghche-mcp
Or in ~/.codex/config.toml:
[mcp_servers.taaghche]
command = "uvx"
args = ["taaghche-mcp"]
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"taaghche": { "command": "uvx", "args": ["taaghche-mcp"] }
}
}
Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
It is a standard stdio MCP server: run uvx taaghche-mcp, or pip install taaghche-mcp and run taaghche-mcp.
All 12 tools are annotated readOnlyHint: true and return compact JSON.
Find and read a book
| Tool | What it does |
|---|---|
tg_search | Search ebooks and audiobooks by title, author or topic: price, discount, rating, format; sort, discounted, free, subscription and price-range options |
tg_suggest | Search-box typeahead: up to about 10 matching book titles with id and publisher |
tg_book | One book: price, discount, format, pages or duration, people, rating breakdown, categories, ISBN |
tg_reviews | Reader reviews, most liked first: rating, text, likes, reply count; replies to one review |
tg_similar | Related books as separate lists (similar works, same author, same publisher) |
Browse
| Tool | What it does |
|---|---|
tg_categories | Category tree: top-level groups and standalone categories with ids and slugs; group adds one group's sub-categories |
tg_browse | List books of a category (or the whole catalog), 16 per page, by sort, format and price ceiling |
tg_bestsellers | Hottest books now (Taaghche's trending ranking), overall or per category |
tg_new_releases | Newest books, most recently added first, overall or per category |
tg_free_books | Free books and audiobooks (price 0), most downloaded first by default |
tg_author | An author's profile (nationality, life dates, bio) and their books, 16 per page |
tg_publisher | A publisher's description and its books, 16 per page |
AI agent (Claude, Cursor, Copilot, ...)
│
│ MCP over stdio
▼
taaghche-mcp (runs on your machine)
│
│ HTTPS
├──────▶ get.taaghche.com books, reviews, lists, search
├──────▶ explore.taaghche.com title suggestions
└──────▶ taaghche.com home page (category menu)
taaghche-mcp runs locally and calls the same public endpoints the taaghche.com website uses. There is no hosted
server in between and no API key. Requests go out through a Chrome-impersonating client, at most 2 at a time with a
little jitter. Book pages, the home page and slug pages are cached for 5 minutes, and a failed request is retried up to twice.
It only reads.
58500 in the API and ۵۸,۵۰۰ تومان on the page). final_price is what you pay, price is before discount, discount_pct a whole percent, free is true for 0.tg_search applies min_price, max_price and free_only to the results it scans (up to 5 pages of 12); the browse tools, tg_author and tg_publisher do the same with max_price (up to 5 pages of 16). scanned tells how many books were looked at; with sort="cheapest" the ceiling is exact and the scan stops early. Only free and discounted lists are filtered by the site.tg_search returns 12 books per page, the browse tools and tg_author / tg_publisher 16. Pass next_cursor back as cursor with the same other arguments. tg_reviews pages with offset.tg_search(sort="bestselling").in_subscription marks books included in it; the price is for buying the book permanently._fa are Persian (Jalali). Audiobooks have duration_min and narrators, ebooks have pages.TAAGHCHE_MCP_PROXY; system proxy variables are ignored on purpose. If the site shows a bot check, an optional headless-browser extra helps: pip install "taaghche-mcp[browser]", then patchright install chromium.Taaghche has no documented public API. taaghche-mcp is an unofficial MCP server with 12 read-only tools that calls
the same public endpoints the taaghche.com website uses, so Claude, Cursor or Copilot can search books and read prices
and reviews.
It is unofficial, open source (MIT) and free. It is read-only, needs no account or API key, and runs on your machine with no hosted server in between.
No. It only reads public catalog data: search, prices, reviews and lists. Buying and reading happen on taaghche.com or in the Taaghche app.
Toman. The API already returns Toman, so nothing is converted. final_price is what the customer pays.
Yes. tg_search and the browse tools take a format (ebook, audiobook or any), and tg_free_books lists free
audiobooks as well as free ebooks. Audiobook results carry the listening time and narrators.
Yes, with max_price (and min_price on search). Taaghche has no price filter of its own, so the server scans up to
5 pages of results and filters them; the reply's scanned field says how many books were checked.
The site's "hot" ranking. Taaghche does not publish sales numbers, so this is its trending order, not a sales count.
Add the server with claude mcp add taaghche -- uvx taaghche-mcp, or use the matching config in
Quick start, then ask in plain language, in Persian or English.
npx @modelcontextprotocol/inspector uvx taaghche-mcp
| Variable | Default | Meaning |
|---|---|---|
TAAGHCHE_MCP_PROXY | unset | Optional HTTP proxy URL for requests to taaghche.com, e.g. http://user:pass@host:port; system proxy settings are ignored. A comma-separated list is used one at a time: the next proxy takes over when one is blocked (403/429) or cannot connect |
taaghche-mcp یک سرور MCP غیررسمی و فقطخواندنی برای طاقچه (taaghche.com)، فروشگاه کتاب الکترونیکی و کتاب صوتی ایران است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد در حدود ۲۲۰ هزار کتاب جستجو کند، قیمت و قالب نسخهها را مقایسه کند، نظر خوانندگان را بخواند و پرفروشها، تازهها و کتابهای رایگان را ببیند.
چه کارهایی میکند
نکتهها
نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add taaghche -- uvx taaghche-mcp
در Claude Desktop، Cursor و بقیه برنامهها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسشها
کلیدواژهها: طاقچه، کتاب الکترونیکی، کتاب صوتی، خرید کتاب، کتاب رایگان، پرفروشترین کتابها، قیمت کتاب، نظر درباره کتاب.
git clone https://github.com/sepehr071/taaghche-mcp && cd taaghche-mcp
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q # offline, on recorded fixtures
uv run python -m pytest -m live -q # calls the real Taaghche API
uv build
Tools live in src/taaghche_mcp/books.py and browse.py; each is a typed async function with a docstring that tells
the agent when to use it. Issues and PRs are welcome.
Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions publishes to PyPI.
Unofficial and not affiliated with or endorsed by Taaghche. It is read-only and uses the public endpoints of the taaghche.com website, which can change without notice. Book data and review text belong to Taaghche and its users.
Built and maintained by Sepehr Radmard (سپهر رادمرد). Connect on LinkedIn or follow @sepehr071 on GitHub for more MCP servers for Iranian websites, all listed in iran-mcp. If this saves you time, a star on the repo helps other people find it.
FAQs
Unofficial read-only MCP server for Taaghche: search Persian ebooks and audiobooks, compare prices and formats, read reviews, browse bestsellers, new and free books.
The pypi package taaghche-mcp receives a total of 562 weekly downloads. As such, taaghche-mcp popularity was classified as not popular.
We found that taaghche-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.