Ganjoor MCP Server
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HOST | No | HTTP bind address. Default: `127.0.0.1`. | |
| HTTP | No | Set to `true` to serve streamable HTTP instead of stdio. Default: (unset). | |
| PORT | No | HTTP port. Default: `3000`. | |
| ALLOWED_ORIGINS | No | Extra allowed `Origin` values, comma-separated. Default: (empty). | |
| GANJOOR_API_BASE_URL | No | Upstream API base URL — point at a local RMuseum instance for development. Default: `https://api.ganjoor.net`. | |
| GANJOOR_SITE_BASE_URL | No | Front-end base used to build clickable links. Default: `https://ganjoor.net`. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Ganjoor (گنجور) is the largest public archive of Persian classical poetry. This server exposes the read-only, public parts of the Ganjoor REST API (https://api.ganjoor.net) for browsing poets, collections, poems, verses, prosody/rhyme analysis, recitations, commentary, and related-people graphs.
Key ideas:
"Poet" (شاعر) has an id and a URL slug, e.g. Hafez is poet id 2, slug "/hafez".
"Category" (بخش/دیوان) groups poems inside a poet's work. Root category id for Hafez is 9.
"Poem" (شعر) has an id and a full URL such as "/hafez/ghazal/sh494".
Poem text is Persian and right-to-left; return it verbatim, never transliterate or translate it unless the user explicitly asks.
Nearly every tool accepts
response_format: "markdown" (default, readable) or "json" (structured, for programmatic use).
Workflow tip: browse with ganjoor_list_poets / ganjoor_get_poet / ganjoor_get_category, find a poem with ganjoor_search_poems, then read it with ganjoor_get_poem (by URL) or ganjoor_get_poem_by_id.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| ganjoor_list_poetsA | List all poets published on Ganjoor.net, including their biographies. Returns one row per poet with: id, name, nickname, URL slug, root category id, birth/death years (Hijri), and birth/death places. Use this first when you need to translate a poet's name to a numeric id for other Ganjoor tools. Args:
Returns: A paginated poet list. For JSON: { total, count, page, page_size, has_more, next_page, poets: [{ id, name, nickname, full_url, root_cat_id, birth_year_hijri, death_year_hijri, birth_place, death_place }] } Examples:
Notes:
|
| ganjoor_get_poetA | Get a single poet's full profile (including biography) by numeric id or URL slug. Use this to turn a slug like "/hafez" into the numeric poet id, or to read a poet's biography and catalogue of works. Args:
Returns: Poet profile with id, name, nickname, biography, birth/death (Hijri + places), plus for JSON: { id, name, nickname, biography, birth_year_hijri, death_year_hijri, birth_place, death_place, full_url, cats: [{ id, title, full_url, cat_type }] } Examples:
Notes:
|
| ganjoor_get_poets_by_centuryA | Get every Ganjoor poet grouped into historical half-centuries. The first group (id 0) holds the "pinned"/featured poets shown on the Ganjoor home page. Each later group carries a name, an approximate Gregorian year range, and the poets active in that period. Args:
Returns: For JSON: { centuries: [{ id, name, start_year, end_year, poet_count, poets: [{ id, name, full_url }] }] } Examples:
Notes:
|
| ganjoor_list_booksA | List Ganjoor books (named collections such as دیوان حافظ or غزلیات سعدی), alphabetically. Every returned entry is a category of type "Book". Use the resulting category id with ganjoor_get_category to browse the poems inside, or with ganjoor_get_category_poems to list them. Args:
Returns: For JSON: { count, page, page_size, has_more, next_page, books: [{ id, name, poet_id, poet_name, full_url }] } Examples:
Notes:
|
| ganjoor_get_categoryA | Get a Ganjoor category (a book, section, or sub-collection) by numeric id. A category is the container for poems inside a poet's work — for example Hafez's ghazals (category id 10) or Rumi's Masnavi. The response includes the breadcrumb path, the direct children (sub-sections), and optionally the poems it contains. Args:
Returns: Category metadata: id, title, breadcrumb, description, table-of-contents style, child categories, and (optionally) contained poems with their ids, titles and URLs. Set include_poems=false to skip the poem list; use ganjoor_list_category_poems when you only want the poems and their total count. Examples:
Notes:
|
| ganjoor_list_category_poemsA | List the poems contained in a Ganjoor category, optionally filtered by the author's name. Args:
Returns: For JSON: { total, count, page, page_size, has_more, next_page, category: { id, title, full_url }, poems: [{ id, title, url_slug, full_url, excerpt }] } Examples:
Notes:
|
| ganjoor_get_category_geotagsA | Get the geographic and historical locations tagged to poems within a Ganjoor category and its descendants. Each tag pairs a place with the Hijri/Gregorian date a poem commemorates, which is how Ganjoor records historical events (a battle, a siege) in poetry. Args:
Returns: For JSON: { total, tags: [{ id, latitude, longitude, lunar_date, gregorian_date, child_cat }] } Examples:
Notes:
|
| ganjoor_get_category_people_graphA | Get the network of historical people relevant to a Ganjoor category or work. Returns every person tagged in a poem under this category's subtree, plus their kinship and affiliation ties one hop out — the data behind Ganjoor's "characters" (شخصیتها) tab. Args:
Returns: For JSON: { node_count, edge_count, nodes: [{ id, name, importance }], edges: [{ from_person_id, to_person_id, relation }] } Examples:
Notes:
|
| ganjoor_search_poemsA | Full-text search across all poems on Ganjoor, optionally scoped to one poet or category. The search matches Persian text inside poem bodies and titles. Use this when you know what the poem says but not what it is called; use ganjoor_list_category_poems when you know the book. Args:
Returns: For JSON: { count, page, page_size, has_more, next_page, poems: [{ id, title, full_title, full_url, plain_text? }] } Examples:
Notes:
|
| ganjoor_semantic_search_poemsA | Meaning-based ("find a poem about...") search over Ganjoor's poetry collection. Use this when you want poems by theme or feeling rather than an exact word. Describe the idea in natural language — in English or Persian — and Ganjoor's embedding search returns the closest verses. Prefer ganjoor_search_poems when you have an exact phrase to look for. Args:
Returns: For JSON: { count, results: [{ id, title, full_title, full_url, plain_text }] } ordered by relevance. Examples:
Notes:
|
| ganjoor_get_poemA | Fetch a complete poem by its Ganjoor URL, including verses, metre, rhyme, and recitations. This is the main way to read a poem. The URL is the same as the browser address on ganjoor.net, e.g. "hafez/ghazal/sh494". Use ganjoor_search_poems or ganjoor_list_category_poems to discover URLs, and ganjoor_get_poem_by_id when you only have a numeric id. Args:
Returns: Poem id, title, full title, poet, book/category path, plain text, and the ordered verse list grouped into couplets. For JSON: { id, title, full_title, full_url, poet, category, couplets_count, verses: [{ couplet_index, position, text }], recitations: [...], next_poem, previous_poem } Examples:
Notes:
|
| ganjoor_get_poem_by_idA | Fetch a complete poem by its numeric Ganjoor id. Same content as ganjoor_get_poem, but keyed on the numeric poem id instead of the URL. Use it when you have an id from search results or another tool and do not want to build a URL. Args:
Returns: Identical shape to ganjoor_get_poem. Examples:
Notes:
|
| ganjoor_get_poem_versesA | Get just the verses of a poem by id — a lightweight alternative to fetching the whole poem. Each verse comes back in order with its couplet index and whether it is the first or second hemi- stich. Optionally restrict to a single couplet. Args:
Returns: For JSON: { poem_id, verse_count, verses: [{ id, order, couplet_index, position, text }] } Examples:
Notes:
|
| ganjoor_get_random_poemA | Get a random poem from Ganjoor, optionally from a specific poet. Args:
Returns: A single complete poem in the same shape as ganjoor_get_poem_by_id. Examples:
Notes:
|
| ganjoor_get_hafez_faalA | Draw a random Hafez ghazal as a Persian divination (فال حافظ). This is the traditional "ask Hafez" reading: one ghazal selected at random, to be interpreted in the context of the question asked. Each call draws a different ghazal. Args:
Returns: A complete Hafez ghazal in the same shape as ganjoor_get_poem_by_id. Examples:
Notes:
|
| ganjoor_get_page_urlA | Resolve any Ganjoor page id (poem, category, or poet) to its public web URL path. Useful when you have a bare numeric id from an index or a citation and need to cite or link it. Args:
Returns: For JSON: { id, url, full_url } Examples:
Notes:
|
| ganjoor_get_redirect_urlA | Resolve a legacy or short Ganjoor URL to its current canonical address. Ganjoor has renamed many sections over the years; this endpoint maps an old path to today's one. Args:
Returns: For JSON: { requested_url, redirect_url, full_url, has_redirect } — redirect_url is null and has_redirect is false when Ganjoor has no redirect for that URL (which includes URLs that are already canonical). Examples:
Notes:
|
| ganjoor_list_rhythmsA | List every Persian prosodic metre (وزن) used in the Ganjoor corpus, with its verse-pattern notation. Use this to translate a metre name into the id Ganjoor uses, or to discover the metre vocabulary before calling ganjoor_find_similar_poems or ganjoor_analyze_poem_rhythm. Args:
Returns: For JSON: { count, page, page_size, has_more, next_page, rhythms: [{ id, rhythm, verse_count }] } Examples:
Notes:
|
| ganjoor_analyze_poem_rhythmA | Detect the prosodic metre (وزن) of a poem by its numeric id. Runs Ganjoor's prosody engine over the poem's verses and returns the matched metre together with its confidence and the competing alternatives considered. Args:
Returns: For JSON: { poem_id, metre: { id, rhythm }, confidence, alternatives: [{ id, rhythm, score }] } Examples:
Notes:
|
| ganjoor_analyze_poem_rhymeA | Detect the rhyme letter (قافیه) and rhyme pattern of a poem by its numeric id. Args:
Returns:
For JSON: { poem_id, rhyme, rhyme_letter, fail_verse } — Examples:
Notes:
|
| ganjoor_find_similar_poemsA | Find poems that share a poem's prosodic metre and rhyme letter — the basis of Ganjoor's "related poems" (شعرهای مرتبط) pages. Two Persian poems matching in metre and rhyme can be read as answers to each other (reply-poetry), so this is also how you trace how one poet answered another. Args:
Returns: For JSON: { count, page, page_size, has_more, next_page, poems: [{ id, title, full_title, full_url, plain_text }] } Examples:
Notes:
|
| ganjoor_get_poem_sectionsA | Get the structural sections of a poem — the stanzas (بند), couplets (مثنوی), and tercets (رباعی) it is built from. Ganjoor models a poem as nested sections so that poetry written in distinct forms within one poem (e.g. a ghazal that closes with a qet'e) can be analysed per-section. Args:
Returns: For JSON: { poem_id, section_count, sections: [{ id, index, number, section_type, verse_type, metre, rhyme }] } Examples:
Notes:
|
| ganjoor_get_sectionA | Get one section of a poem by its section id, including its verses and its own related sections. Args:
Returns: Section metadata, its metre/rhyme, optionally its verses and its related sections. Examples:
Notes:
|
| ganjoor_get_related_sectionsA | Find sections from other poems that match a given poem section in metre and rhyme. This is the section-level counterpart of ganjoor_find_similar_poems and is how Ganjoor links reply-poems and cross-poet allusions at stanza granularity. Args:
Returns: For JSON: { poem_id, section_index, total, related_sections: [{ id, poem_id, section_index, poet_name, full_url }] } Examples:
Notes:
|
| ganjoor_get_couplet_sectionsA | Find which structural sections a specific couplet of a poem belongs to. A verse carries up to four nested section indices; this endpoint resolves one couplet to the stanzas that contain it, which you need when analysing a ghazal's opening or closing section. Args:
Returns: For JSON: { poem_id, couplet_index, sections: [{ id, index, number, section_type, metre, rhyme }] } Examples:
Notes:
|
| ganjoor_get_language_tagged_sectionsA | List poem sections Ganjoor has tagged with a specific language, newest-scoped by poet. Ganjoor tags translated or bilingual stanzas with a language code (for example Args:
Returns: For JSON: { language, count, page, page_size, has_more, next_page, sections: [{ id, poem_id, poem_title, poet_name }] } Examples:
Notes:
|
| ganjoor_search_recitationsA | Search the published audio recitations (روایت) of Ganjoor poems, optionally by reciter or poem. Each recitation is a sung or spoken performance of one poem by a named artist, published on ganjoor.net. Args:
Returns: For JSON: { count, page, page_size, has_more, next_page, recitations: [{ id, poem_id, poem_title, poem_url, artist, title, publish_date, duration_seconds }] } Examples:
Notes:
|
| ganjoor_get_recitationA | Get one published recitation by its numeric id, including its audio file location and poem reference. Args:
Returns: For JSON: { id, poem_id, poem_title, poem_url, title, artist, artist_url, audio_url, publish_date, duration_seconds, review_status } Examples:
Notes:
|
| ganjoor_get_recitation_sync_infoA | Get the per-verse timing map for a recitation, showing when each couplet begins in the audio. Useful for following along with the text while a recitation plays. Args:
Returns: For JSON: { recitation_id, sync_point_count, total_duration_ms, sync_points: [{ verse_order, text, start_time_ms, start_time_seconds }] } Examples:
Notes:
|
| ganjoor_get_poem_recitationsA | List every audio recitation published for one poem. Args:
Returns: For JSON: { poem_id, count, page, page_size, has_more, next_page, recitations: [{ id, artist, title, publish_date, duration_seconds }] } Examples:
Notes:
|
| ganjoor_get_category_top_recitationsA | Get the most-liked recitations within a category — Ganjoor's "top 1" (بهترین) listings for a book. Args:
Returns: For JSON: { cat_id, count, recitations: [{ recitation_id, poem_id, poem_title, artist, score, plain_text? }] } Examples:
Notes:
|
| ganjoor_list_peopleA | List the historical and literary figures Ganjoor has catalogued as related persons (شخصیتها). These are people who appear in a poem's commentary or annotations — rulers, prophets, companions, poets' contemporaries — as distinct from poets themselves. Args:
Returns: For JSON: { total, count, page, page_size, has_more, next_page, people: [{ id, name, birth_year_hijri, death_year_hijri, birth_location, death_location, importance, gender }] } Examples:
Notes:
|
| ganjoor_get_personA | Get one person's full record — biography, dates, places, and external references. Args:
Returns: For JSON: { id, name, description, wiki_url, birth_year_hijri, death_year_hijri, birth_location, death_location, family_tree_caption, machine_generated, importance, gender } Examples:
Notes:
|
| ganjoor_get_person_poemsA | Get every poem Ganjoor has tagged with a given person. This is the strongest link between a historical figure and the poetry about them. Args:
Returns: For JSON: { person_id, total, count, page, page_size, has_more, next_page, poems: [{ id, title, full_url }] } Examples:
Notes:
|
| ganjoor_get_person_relationsA | Get a person's kinship and affiliation edges — parents, siblings, spouses, teachers, and contemporaries. Args:
Returns: For JSON: { person_id, relation_count, relations: [{ id, from_person_id, from_person_name, to_person_id, to_person_name, relation_kind, relation_name }] } Examples:
Notes:
|
| ganjoor_get_person_family_treeA | Get the full connected kinship component reachable from a person — ancestors, descendants, spouses, and siblings. This returns the whole clan cluster, not just one hop, which makes it the right tool for tracing a figure's lineage across generations. Args:
Returns: For JSON: { person_id, root_id, person_count, people: [{ id, name, birth_year_hijri, death_year_hijri, family_tree_caption }], relation_count, relations: [{ person1_id, person1_name, person2_id, person2_name, relation_label }] } Examples:
Notes:
|
| ganjoor_get_recent_commentsA | Get the most recent published reader comments across Ganjoor, optionally filtered. Comments are scholarly notes attached to a specific couplet of a poem. Args:
Returns: For JSON: { count, page, page_size, has_more, next_page, comments: [{ id, poem_id, poem_title, couplet_index, user, text, date, has_owner_response }] } Examples:
Notes:
|
| ganjoor_list_faq_categoriesA | List the Ganjoor site's published FAQ (پرسشهای متداول) categories. These are editorial explanations of how Ganjoor works — text sourcing, version differences, contribution rules. Args:
Returns: For JSON: { count, categories: [{ id, title, description, item_count }] } Examples:
Notes:
|
| ganjoor_get_faq_itemsA | Get every published question-and-answer in a Ganjoor FAQ category. Args:
Returns: For JSON: { cat_id, total, count, page, page_size, has_more, next_page, items: [{ id, question, answer, answer_excerpt }] } Examples:
Notes:
|
| ganjoor_get_faq_itemA | Get one Ganjoor FAQ entry by its numeric id. Args:
Returns: For JSON: { id, category_id, question, answer, answer_excerpt, pinned } Examples:
Notes:
|
| ganjoor_get_poem_imagesA | Get the manuscript and facsimile images Ganjoor holds for a poem. These are photographs of the physical manuscripts, with a thumbnail and a full-resolution link per image — useful for checking a textual variant against its source. Args:
Returns: For JSON: { poem_id, image_count, images: [{ id, url, thumbnail_url, alt, description }] } Examples:
Notes:
|
| ganjoor_get_poem_quoted_poemsA | Get the poems that a given poem quotes or alludes to, and the poems that quote it. Matching in metre and rhyme is common in Persian poetry — poets answer each other by reusing the other's metre and rhyme. This endpoint maps those links in both directions. Args:
Returns: For JSON: { poem_id, total, returned, quotes: [{ id, related_poem_id, related_poet_name, related_poem_title, related_poem_url, is_prior, quoted_couplet, quoting_couplet, claimed_by_both, note }] } Examples:
Notes:
|
| ganjoor_get_poem_effective_correctionsA | Get the editorial corrections applied to a poem's text — the before/after record of every fix. Useful for understanding why the text on Ganjoor differs from an older printed edition. Args:
Returns: For JSON: { poem_id, correction_count, corrections: [{ id, verse_order, text, original_text }] } Examples:
Notes:
|
| ganjoor_get_poem_geotagsA | Get the geographic and historical locations tagged to a single poem. A geo tag pins a poem to a place and to the Hijri/Gregorian date it commemorates — for instance a poem about a battle fought at a named site. Args:
Returns: For JSON: { poem_id, tag_count, tags: [{ id, latitude, longitude, lunar_date, gregorian_date }] } Examples:
Notes:
|
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 44 tools
Most tools target distinct resources or actions, and the descriptions explicitly distinguish similar ones such as ganjoor_get_poem, ganjoor_get_poem_by_id, and ganjoor_get_poem_verses. However, the related-poem cluster (quoted poems, similar poems, related sections) and multiple recitation retrieval tools still create some potential for misselection.
Every tool uses the same ganjoor_ prefix and consistent snake_case verb_noun pattern, such as ganjoor_list_poets, ganjoor_search_poems, and ganjoor_get_recitation. Minor variations like get_poem_by_id do not break the predictable convention.
At 44 tools, the surface is far beyond a typical well-scoped MCP server, and many endpoints are highly niche (poem corrections, geotags, people graph, recitation sync, language-tagged sections). While each maps to a real upstream capability, the set feels like an API mirror rather than a curated tool surface.
For a read-only poetry domain, coverage is extensive: poems, poets, categories, search, sections, recitations, people, FAQ, imagery, geotags, rhythm, rhyme, and corrections are all represented. There are no obvious dead ends for the stated Ganjoor domain.