iranketab-mcp

Read-only MCP server for iranketab.ir: search books, compare translations and editions, prices in Toman, stock, ratings and reader comments. No key needed.

Modelled on digikala-mcp. Not affiliated with iranketab.

Connect

Hosted endpoint (Streamable HTTP, stateless, no key): https://iranketab-mcp.vercel.app/mcp

{ "mcpServers": { "iranketab": { "url": "https://iranketab-mcp.vercel.app/mcp" } } }

claude mcp add --transport http iranketab https://iranketab-mcp.vercel.app/mcp

Local (stdio). This is faster from inside Iran, because the hosted copy runs in Frankfurt and fetches from iranketab take 2-10 s there on a cache miss:

npm install && npm run build
claude mcp add iranketab -- node "$PWD/dist/index.js"

Then ask: "which translation of Crime and Punishment is best rated and in stock?", "cheapest White Nights that isn't abridged", "what did Soroush Habibi translate?", "bestsellers in Russian literature".

Related MCP server: kvartirabooks-mcp

Tools

All tools carry readOnlyHint. Every book_* tool accepts a work id or an edition id.

How it works

agent --stdio or POST /mcp--> iranketab-mcp --HTTPS, 1 req / 500ms--> www.iranketab.ir

src/server.ts defines the tools once. src/index.ts serves them over stdio, and src/web.ts serves them as a web-standard Request -> Response handler (stateless Streamable HTTP with JSON responses, CORS, and /health). On Vercel, api/mcp.ts and api/health.ts wrap that handler. The functions run in fra1 (Frankfurt), the region closest to Iran.

iranketab has no public API. Two sources are used:

• HTML pages, parsed with node-html-parser:

  • /result/{term}?t=کتاب&s=N for search

  • /book/{id} for a book (one work, N editions as div#p-{editionId} plus a details popup)

• The site's own ListView JSON:

  • /comment/list for comments

  • /tag/filter, /profile/filter, /brand/filter for listings

Details that matter:

• Prices are Toman on the page and in listing JSON. The JSON-LD Offer is Rial (IRR) and is not used.

• The JSON-LD rating belongs to a single edition (White Nights: 3.5 from 27 votes, while its most-read edition has 4.17 from 163). The work rating here is the vote-weighted mean across editions, and edition ratings from under 3 votes are reported as null.

• Stock has three states: in_stock (iranketab's warehouse), publisher_stock (ordered from the publisher, slower) and out_of_stock.

• Listing entries are editions. /book/{editionId} redirects to the work.

• Unknown book ids return HTTP 200 with an empty page (a soft 404). This is detected as "no JSON-LD and no editions".

• Parse JSON-LD with rawText, not text: text decodes 
 into control characters that JSON.parse rejects.

• Hosting outside Iran is slow on a cache miss. iranketab serves foreign visitors through Cloudflare, not ArvanCloud. Measured from Vercel fra1: a book page takes about 2 s uncached and a search about 10 s. Cloudflare Workers in Paris took 7-12 s. Cached calls take about 0.5 s.

• Politeness:

  • requests are serialised 500ms apart

  • failures are retried with jittered backoff (up to 3 tries, honouring retry-after)

  • responses are cached for 30 minutes, so details → editions → comments on one book costs one page fetch

Deploy

npx vercel deploy          # preview
npx vercel deploy --prod   # production

vercel.json pins the region, caps functions at 120 s, and maps /mcp and /health to api/. The Hobby plan is enough: CPU is billed only while it is active, and the up-to-10 s upstream waits don't count.

Develop

npm test        # offline parser tests against saved pages in test/fixtures
npm run smoke   # live end-to-end: spawns the server, calls all 9 tools
MCP_URL=https://iranketab-mcp.vercel.app/mcp npm run smoke   # same, against a deployment
npm run serve   # the HTTP handler locally on http://localhost:3000/mcp
npm run dev     # stdio server from source

When the site changes markup, npm run smoke goes red. Re-save a fixture and npm test shows which field broke.