ganjoor-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ganjoor-mcp Which poem is «الا یا ایها الساقی ادر کاسا و ناولها» from, and what does it mean?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ganjoor-mcp: Ganjoor (گنجور) Persian poetry MCP server for AI agents
ganjoor-mcp is an unofficial, read-only MCP server that lets an AI agent read, search and explain classical Persian poetry on Ganjoor (گنجور, ganjoor.net), the open library of 240+ poets and 139,000 poems. Its 18 tools search poems by words or by meaning, find the poem a quoted line comes from, read a poem with the plain-Persian meaning of every couplet, browse poets and books, and explore meters, rhymes, recitations, rhetorical devices, word use, people, places and manuscript scans. No API key or account is needed; it works in Claude, Cursor, Copilot and any other MCP client.
For AI agents · Quick start · Tools · Limits · فارسی
For AI agents
What: unofficial MCP server (model context protocol) for ganjoor.net: full-text and semantic poem search, quoted-line lookup, poems with couplet meanings and summaries, poets, books, Hafez faal, meters and rhymes, recitations with verse timing, literary devices, word frequency, people and family trees, places, museum manuscripts, Tajik Cyrillic text.
Install:
uvx ganjoor-mcporclaude mcp add ganjoor -- uvx ganjoor-mcp. Transport: stdio. Needs uv (Python 3.10+).Auth: none. Optional
GANJOOR_MCP_PROXY(HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.Access: read-only. It cannot log in, comment, vote or upload. Works from any country.
Tools: 18, all prefixed
gj_. Typical sequences:gj_semantic_searchorgj_search->gj_poem;gj_find_verse;gj_poets->gj_poet->gj_book->gj_poem->gj_poem_extras;gj_meters->gj_similar;gj_faal.Use when: the user quotes a Persian couplet, asks what a poem means, wants a poem on a theme, asks about a poet, a meter, a recitation or a manuscript, or wants a Hafez faal.
Output: compact JSON. Poem text is Persian and verbatim; numbers are ASCII. Meanings that start with «هوش مصنوعی:» are AI-written (Ganjoor regenerated them with Claude Opus 5.5 in November 2026); others are written by people.
Related MCP server: PoetryDB MCP Server
Quick start
You need uv. No API key or account.
Claude Code:
claude mcp add ganjoor -- uvx ganjoor-mcpClaude Desktop, Cursor, VS Code and other clients:
{
"mcpServers": {
"ganjoor": { "command": "uvx", "args": ["ganjoor-mcp"] }
}
}Example prompts:
"Which poem is «الا یا ایها الساقی ادر کاسا و ناولها» from, and what does it mean?"
"Find Persian poems about the passing of time and seizing the moment."
"Give me a Hafez faal and explain it."
غزلهایی هموزن و همقافیهٔ این غزل سعدی پیدا کن.
خوانشهای غزل اول حافظ را با لینک صوتی بیاور.
Real answer (21 Nov 2026): gj_find_verse(text="الا یا ایها الساقی ادر کاسا و ناولها") returned Hafez, ghazal 1, couplet 1, and listed five later poems that quote the line (Jami, Helali and others) under also_in.
Tools
Tool | What it returns |
| Poems containing all the given words, with the matching couplet |
| Poems close in meaning to a theme or question, with score, summary and opening couplets |
| The poem and couplet a quoted line comes from, with its meaning and other poems quoting it |
| A poem by id or ganjoor.net path: couplets with meanings, summary, meter, rhyme, source, previous/next |
| A poem's recitations, images, songs, related and quoting poems, comments |
| Poets with ids, years and eras, filtered by name or century |
| A poet's biography and books |
| A book or section: sub-sections and poems, paged |
| A Hafez faal, or a random poem (optionally of one poet), with meanings |
| Poems in Tajik Cyrillic script: search, or one poem |
| Poetic meters with couplet counts |
| Poems sharing a meter and rhyme, with their first couplet |
| Recitations of a poem or book, or the newest, with mp3 links, votes and verse timing |
| Rhetorical devices and literary tags of a poem, or lookups and stats |
| Word frequency in a poet's work or a book, or the count of one word |
| People and characters: info, relations, family trees, a book's cast |
| Places named in poems, with coordinates |
| Manuscript and artifact scans from the Ganjoor museum |
Limits
Semantic search runs on a separate Ganjoor service (ganjgah.ir) that is sometimes down; the tool then tries api.ganjoor.net and falls back to word search, saying so in
note.Word search is an AND match on normalized text: all words must appear. Quote the line or use fewer words.
Recitations carry no duration (only file size); verse timing is per hemistich for the best-voted recitation.
Literary-device tags cover only part of the corpus (mostly Hafez so far). Relation types
siblingandspouseingj_peopleare inferred, not documented by the API.Long sections (Shahnameh, Masnavi) return 80 couplets by default; raise
max_coupletsup to 500.
فارسی
ganjoor-mcp یک سرور MCP غیررسمی و فقطخواندنی برای گنجور (ganjoor.net) است. با آن یک عامل هوش مصنوعی میتواند شعرها را با واژه یا با معنا جستوجو کند، شعرِ یک بیتِ از حفظخوانده را پیدا کند، شعر را با معنی سادهی هر بیت بخواند، میان شاعران و کتابها بگردد، فال حافظ بگیرد و وزنها، قافیهها، خوانشها، آرایههای ادبی، بسامد واژهها، شخصیتها، مکانها و نسخههای خطی موزه را ببیند. بدون حساب کاربری و کلید API کار میکند. نصب در Claude Code:
claude mcp add ganjoor -- uvx ganjoor-mcpDevelopment
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q # offline tests on recorded fixtures
uv run python -m pytest -m live -q # live calls to api.ganjoor.net and ganjgah.irReleases: bump the version in pyproject.toml and server.json, run uv lock, then push a v* tag; GitHub Actions publishes to PyPI.
Disclaimer
Unofficial and not affiliated with or endorsed by Ganjoor. It is read-only and uses the public API of ganjoor.net, which can change without notice. The poems are in the public domain; the compilation, meanings, summaries, recitations and scans are the work of Ganjoor and its contributors: please credit ganjoor.net when you use them, and consider supporting Ganjoor.
Author
Built and maintained by Sepehr Radmard (سپهر رادمرد). LinkedIn · GitHub · more servers in iran-mcp.
مجوز استفاده (License)
استفادهٔ شخصی و غیرتجاری رایگان است. استفاده در شرکت، محصول پولی یا پروژهٔ مشتری به مجوز تجاری نیاز دارد؛ از راه لینکدین یا گیت‌هاب با سپهر رادمرد تماس بگیرید. متن کامل: PolyForm Noncommercial 1.0.0.
Free for personal and non-commercial use under the PolyForm Noncommercial License 1.0.0. Using it in a company, a paid product or a client project needs a commercial license: contact Sepehr Radmard on LinkedIn or GitHub.
Available Tools
18 toolsgj_bookBrowse a bookARead-onlyIdempotent
Sub-books and the poems of one book or section, each with its first couplet, paged by 30.
Open a poem with gj_poem.
Inputs: cat_id (required), page.
gj_faalHafez faal or random poemARead-onlyIdempotent
Draw a Hafez faal (a random ghazal of Hafez) or, with random=True, a random poem, read with meanings.
Same output as gj_poem.
Inputs: random, poet_id.
gj_find_verseFind the poem of a quoted lineARead-onlyIdempotent
Locate which poem and couplet a quoted line comes from, with the couplet's meaning.
Spelling differences (ye/kaf, ZWNJ, diacritics, punctuation) are ignored.
Inputs: text (required).
gj_literaryLiterary devicesARead-onlyIdempotent
Show rhetorical devices (آرایه: tashbih, esteare...) and concepts tagged in poems; coverage is partial, mostly Hafez.
Inputs: tag, view, cat_id, poem_id, +1 more.
gj_metersPoetic metersARead-onlyIdempotent
List poetic meters (وزن) with couplet counts, biggest first; filter by name. Feed a name or id to gj_similar.
Inputs: query.
gj_museumMuseum manuscriptsARead-onlyIdempotent
Browse Ganjoor museum manuscripts and scans (گنجینه): search, one manuscript's details, or one page image.
Inputs: item, page, slug, query.
gj_peoplePeople and charactersBRead-onlyIdempotent
Look up people and characters of epic poems (Shahnameh...): search, relations, family tree, or a book's cast.
Inputs: id, view, query, cat_id.
gj_placesPlaces in poemsBRead-onlyIdempotent
Find geotagged places (locations with latitude and longitude) named in poems, a book, or by name.
Inputs: query, cat_id, poem_id.
gj_poemRead a poemARead-onlyIdempotent
Read a poem: text by couplet with meanings, summary, meter, rhyme, source and previous/next poem.
Meanings starting with «هوش مصنوعی:» are AI-written. Give id or url.
Inputs: id, url, meanings, max_couplets.
gj_poem_extrasPoem recitations, replies and commentsARead-onlyIdempotent
Recitations with mp3 links, manuscript images, songs, related poems, quoting poems and reader comments.
Each part is trimmed (about 10 items).
Inputs: id (required), parts.
gj_poetPoet biography and booksARead-onlyIdempotent
A poet's biography (shortened) and the top-level books to open with gj_book.
Give id or url.
Inputs: id, url.
gj_poetsList poetsARead-onlyIdempotent
List poets with ids, nicknames, life years (Hijri) and birthplace, filtered by name or century.
Without a query only the first 50 are shown.
Inputs: era, query.
gj_recitationsRecitationsARead-onlyIdempotent
List poem recitations (خوانش) with reciter, mp3 link, size and votes; give exactly one of poem_id, cat_id, latest.
Inputs: limit, cat_id, latest, poem_id, +1 more.
gj_searchSearch poems by wordsARead-onlyIdempotent
Full-text search of poems by the words they contain, with the matching couplet.
All words must appear in the poem. Use gj_semantic_search to search by meaning instead.
Inputs: query (required), page, cat_id, poet_id.
gj_semantic_searchSearch poems by meaningARead-onlyIdempotent
Find poems by meaning or theme (embedding search), with score, summary and first couplets.
Falls back to full-text search when the semantic index is down.
Inputs: query (required), top_k.
gj_similarPoems with same meter and rhymeARead-onlyIdempotent
Find poems that share a meter and rhyme, with their first couplet; 10 per page.
Inputs: meter (required), page, cat_id, poet_id, +1 more.
gj_tajikTajik Cyrillic poemsARead-onlyIdempotent
Search or read poems in Tajik Cyrillic transliteration (titles Cyrillic, poet names Persian).
Give query to search, or poem_id to read one poem.
Inputs: page, query, poem_id.
gj_wordsWord frequencyARead-onlyIdempotent
Count word use in a poet's or book's poems: the most frequent words, or how often one word appears.
Inputs: word, limit, cat_id, poet_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools target clearly different resources (poems, poets, books, meters, places, people, museum), and descriptions explicitly cross-reference alternatives (gj_search vs gj_semantic_search vs gj_find_verse, gj_poem vs gj_book). The main soft spots are gj_recitations overlapping with gj_poem_extras (both surface recitations/mp3s) and gj_poem overlapping with gj_poem_extras, but the guidance in the descriptions mostly resolves these.
Every tool uses the same gj_ snake_case convention, which is highly predictable. However, the second token mixes nouns (gj_poem, gj_meters, gj_places) with verbs/actions (gj_search, gj_find_verse), so it is not a strict verb_noun pattern, though it reads consistently enough.
18 tools is on the heavier side of the ideal band, but each maps to a genuinely distinct facet of a poetry platform (search variants, poem/book/poet navigation, meters, recitations, museum, people, places). Nothing feels purely redundant, though consolidation of gj_recitations into gj_poem_extras would tighten it.
The surface covers the full read lifecycle: poet -> book -> poem, plus full-text and semantic search, verse lookup, meter/rhyme discovery, recitations, manuscripts, commentary, and domain extras. Gaps are minor, e.g. no explicit category/tag listing tool and no write operations, which is expected for a read-only corpus API.
Maintenance
Related MCP Connectors
Free web search, 130M+ business records, local search, weather and travel data for AI agents.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Search and fetch tools over the pages of pournasserian.com, Amir Pournasserian's personal website: his writing on MCP, AI agents and RAG, his experience, case studies and open-source projects. No authentication. Runs the open-source mcp-my-site.
Search 16,000+ API operations and 95 built tools by need, then call any of them by name
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables exploring and retrieving classic poems from PoetryDB via 12 MCP tools for catalog, search, and discovery, including by author, title, lines, and poetic forms.1250 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to explore a public-domain poetry collection by searching poems by title, finding poems whose lines contain a given phrase, pulling one or more random poems, and listing available authors. It returns full poem text with author and line-count details, and works either through a hosted gateway or as a local stdio server without an account.96 npmMIT
- AlicenseAqualityBmaintenanceEnables AI agents to search and compare Persian book editions, ratings, reviews, prices, authors, translators, publishers, and bestseller or prize lists from Iranketab in a read-only way without an API key.1379 PyPIPolyForm Noncommercial 1.0.0
- AlicenseAqualityBmaintenanceEnables AI agents to search Persian ebooks and audiobooks on Fidibo, compare prices in Toman, find free and Fidibo Plus titles, read reviews, and browse bestsellers, new releases, authors and publishers — read-only, with no account or API key required.11150 PyPIPolyForm Noncommercial 1.0.0