Skip to main content

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.

PyPI Python CI License: PolyForm Noncommercial

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-mcp or claude 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_search or gj_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.

Quick start

You need uv. No API key or account.

Claude Code:

claude mcp add ganjoor -- uvx ganjoor-mcp

Claude 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
gj_search Poems containing all the given words, with the matching couplet
gj_semantic_search Poems close in meaning to a theme or question, with score, summary and opening couplets
gj_find_verse The poem and couplet a quoted line comes from, with its meaning and other poems quoting it
gj_poem A poem by id or ganjoor.net path: couplets with meanings, summary, meter, rhyme, source, previous/next
gj_poem_extras A poem's recitations, images, songs, related and quoting poems, comments
gj_poets Poets with ids, years and eras, filtered by name or century
gj_poet A poet's biography and books
gj_book A book or section: sub-sections and poems, paged
gj_faal A Hafez faal, or a random poem (optionally of one poet), with meanings
gj_tajik Poems in Tajik Cyrillic script: search, or one poem
gj_meters Poetic meters with couplet counts
gj_similar Poems sharing a meter and rhyme, with their first couplet
gj_recitations Recitations of a poem or book, or the newest, with mp3 links, votes and verse timing
gj_literary Rhetorical devices and literary tags of a poem, or lookups and stats
gj_words Word frequency in a poet's work or a book, or the count of one word
gj_people People and characters: info, relations, family trees, a book's cast
gj_places Places named in poems, with coordinates
gj_museum 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 sibling and spouse in gj_people are inferred, not documented by the API.
  • Long sections (Shahnameh, Masnavi) return 80 couplets by default; raise max_couplets up to 500.

فارسی

ganjoor-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای گنجور (ganjoor.net) است. با آن یک عامل هوش مصنوعی می‌تواند شعرها را با واژه یا با معنا جست‌وجو کند، شعرِ یک بیتِ از حفظ‌خوانده را پیدا کند، شعر را با معنی ساده‌ی هر بیت بخواند، میان شاعران و کتاب‌ها بگردد، فال حافظ بگیرد و وزن‌ها، قافیه‌ها، خوانش‌ها، آرایه‌های ادبی، بسامد واژه‌ها، شخصیت‌ها، مکان‌ها و نسخه‌های خطی موزه را ببیند. بدون حساب کاربری و کلید API کار می‌کند. نصب در Claude Code:

claude mcp add ganjoor -- uvx ganjoor-mcp

Development

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.ir

Releases: 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)

استفادهٔ شخصی و غیرتجاری رایگان است؛ برای استفادهٔ تجاری با سپهر رادمرد تماس بگیرید. Free for personal and non-commercial use; commercial use needs a 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.

Metadata

Release files for ganjoor-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ganjoor-mcp 0.1.0
File Size Uploaded Provenance Actions
ganjoor_mcp-0.1.0.tar.gz 147.5 kB With provenance Details for ganjoor_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ganjoor-mcp 0.1.0
File Interpreter ABI Platform Actions
ganjoor_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for ganjoor_mcp-0.1.0-py3-none-any.whl

Total release size: 177.2 kB

Release files / ganjoor_mcp-0.1.0.tar.gz

Download URL ganjoor_mcp-0.1.0.tar.gz
Size 147.5 kB
Tags Source
SHA-256 checksum
How to use checksums
af25d054800123bc1b232e0faef266e4256622cee20f61ae0bb11c3bbfba4240
BLAKE2b-256 checksum
How to use checksums
49a1f33441e3b3b5ac39225e28090503b472d91956fc93da9fc1133786a18f46
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / ganjoor_mcp-0.1.0-py3-none-any.whl

Download URL ganjoor_mcp-0.1.0-py3-none-any.whl
Size 29.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
896b35dc63e0cfd0e905047a1a9484ba621eff5f1473bc589585e07fae406d8b
BLAKE2b-256 checksum
How to use checksums
35584deb31c5ed00856fcb0228717ef01b1715368cc36e17413a2398659f4633
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for ganjoor-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ganjoor_mcp-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page