Ganjoor MCP Server

Name: Ganjoor MCP Server
Author: Ganjoor

Read-only access to the Ganjoor archive of Persian classical poetry: poets, poems, metre and recitations

By Ganjoor TypeScript Local · stdio Knowledge and memory Web search

GitHub npm Website

27 popularity score ★ 7 ↓ 90/wk

Connect your client

Local (container)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

FirstTerminal

git clone https://github.com/ganjoor/ganjoor-mcp-server.git
cd ganjoor-mcp-server
docker build -t ganjoor-mcp .

Claude CodeTerminal

claude mcp add ganjoor -- docker run --rm -i ganjoor-mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "ganjoor": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ganjoor-mcp"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "ganjoor": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ganjoor-mcp"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "ganjoor": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ganjoor-mcp"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.ganjoor]
command = "docker"
args = ["run", "--rm", "-i", "ganjoor-mcp"]

Gemini CLITerminal

gemini mcp add --scope user ganjoor docker -- run --rm -i ganjoor-mcp

Local (from source)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

FirstTerminal

git clone https://github.com/ganjoor/ganjoor-mcp-server.git
cd ganjoor-mcp-server
npm install
npm run build

Claude CodeTerminal

claude mcp add ganjoor -- node '<ABSOLUTE_PATH_TO_CLONE>/dist/index.js'

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "ganjoor": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "ganjoor": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "ganjoor": {
      "type": "stdio",
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.ganjoor]
command = "node"
args = ["<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"]

Gemini CLITerminal

gemini mcp add --scope user ganjoor node -- '<ABSOLUTE_PATH_TO_CLONE>/dist/index.js'

Settings 6

`HTTP`	Optional: Set to true to serve streamable HTTP at /mcp instead of stdio.
`PORT`	Optional: HTTP port, 3000 by default.
`HOST`	Optional: HTTP bind address, 127.0.0.1 by default.
`ALLOWED_ORIGINS`	Optional: Comma-separated extra Origin values accepted in HTTP mode; loopback only by default.
`GANJOOR_API_BASE_URL`	Optional: Upstream API address, https://api.ganjoor.net by default.
`GANJOOR_SITE_BASE_URL`	Optional: Site address used to build links, https://ganjoor.net by default.

In a container, a setting goes in with -e NAME=value after docker run.

What it does

Ganjoor MCP Server connects an assistant to the public REST API of Ganjoor (ganjoor.net), a large online archive of classical Persian poetry. Through 44 read-only tools it can list poets and their books, open a category and its poems, fetch a full poem as couplets or just its verses, and run keyword or meaning-based search scoped to a poet or category.

Beyond the texts, it exposes Ganjoor's analysis data: the metre and rhyme of a poem, other poems sharing both (the reply-poem chains of Persian verse), stanza sections, audio recitations with per-verse timing, manuscript images, editorial corrections, reader comments, the FAQ, and a graph of historical people with kinship trees and geotags. Persian text comes back as written, right-to-left, without transliteration.

Every tool returns markdown by default or JSON (also as structured content) with response_format. List tools page 1-based with page_size capped at 100; replies longer than 25,000 characters are cut and flagged. The source also sets a 30-second timeout on each upstream request (src/constants.ts), which the README does not mention. It runs over stdio by default, or as a stateless streamable HTTP server at POST /mcp when HTTP=true.

What it needs

Runtime	Node.js 18+orDocker

Node.js 18.17 or newer, and a clone of the repository built with npm install and npm run build (the README gives no published package). The Docker route needs Docker and an image built locally from the included Dockerfile. Outbound internet access to api.ganjoor.net. No account or API key.

Limits

Read-only and anonymous: bookmarks, posting comments and submitting corrections are out of scope. ganjoor_semantic_search_poems returns a 503 when Ganjoor's embedding backend is switched off. ganjoor_list_books covers about 168 curated collections and omits some major poets, Hafez included. Paged upstream endpoints report no totals, so total is often missing. Person, place and language tags are incomplete, so an empty result may be a coverage gap. Some dates are approximate and flagged as such. The code advertises version 1.0.0 to clients while package.json and the README give 0.1.0.

Who it suits

Suits anyone working with Persian literature who wants an assistant to look up, quote, analyse or cross-reference classical poems: students, translators, researchers, or developers building Persian-language features. It needs no key and changes nothing, so it is low-friction to try, but it must be built from source since no ready package is named. It only reaches Ganjoor's archive; for poetry in other languages, or for writing to a Ganjoor account, pick something else.

Tools 44

ganjoor_list_poets: Paged list of published poets with biography, dates and places
ganjoor_get_poet: One poet by id or slug, with top-level books and sections
ganjoor_get_poets_by_century: Poets grouped by historical half-century
ganjoor_list_books: Named collections, filtered by poet or name
ganjoor_get_category: A category with its breadcrumb, sub-sections and poems
ganjoor_list_category_poems: Paged poems in a category, optionally filtered by title
ganjoor_get_category_geotags: Places tagged within a category's subtree
ganjoor_get_category_people_graph: Network of people linked to a category
ganjoor_search_poems: Keyword search over poem text, scoped by poet or category
ganjoor_semantic_search_poems: Search poems by meaning rather than exact words
ganjoor_get_poem: Full poem by URL slug, verses paired into couplets
ganjoor_get_poem_by_id: Full poem by numeric id
ganjoor_get_poem_verses: Only the verses of a poem
ganjoor_get_random_poem: Random poem, optionally from one poet
ganjoor_get_hafez_faal: Random Hafez ghazal used for traditional divination
ganjoor_get_page_url: Web address for a poem, category or poet page id
ganjoor_get_redirect_url: Current address for an old Ganjoor URL
ganjoor_list_rhythms: Persian metres with how often each is used
ganjoor_analyze_poem_rhythm: Detects the metre of a poem
ganjoor_analyze_poem_rhyme: Detects a poem's rhyme letter and pattern
ganjoor_find_similar_poems: Poems sharing a metre and rhyme
ganjoor_get_poem_sections: Structural sections of a poem
ganjoor_get_section: One section with its verses and related sections
ganjoor_get_related_sections: Sections elsewhere with the same metre and rhyme
ganjoor_get_couplet_sections: Sections a given couplet belongs to
ganjoor_get_language_tagged_sections: Stanzas marked as written in a non-Persian language
ganjoor_search_recitations: Find audio recitations by reciter, poet or category
ganjoor_get_recitation: One recitation and its audio link
ganjoor_get_recitation_sync_info: Per-verse timings for a recitation
ganjoor_get_poem_recitations: All recitations of one poem
ganjoor_get_category_top_recitations: Highest-voted recitations in a category
ganjoor_list_people: Historical and literary figures in the people graph
ganjoor_get_person: A person's biography, dates and places
ganjoor_get_person_poems: Poems tagged with a person
ganjoor_get_person_relations: A person's kinship and affiliation links
ganjoor_get_person_family_tree: Whole connected family tree from one person
ganjoor_get_recent_comments: Latest published reader comments
ganjoor_list_faq_categories: Categories of the editorial FAQ
ganjoor_get_faq_items: All questions and answers in one FAQ category
ganjoor_get_faq_item: One FAQ entry by id
ganjoor_get_poem_images: Manuscript and facsimile images of a poem
ganjoor_get_poem_quoted_poems: Poems a poem quotes and poems that quote it
ganjoor_get_poem_effective_corrections: Record of editorial text corrections to a poem
ganjoor_get_poem_geotags: Places and dates tagged to a poem

Popularity

27 popularity score

★ 7 ↓ 90/wk

GitHub stars	7	10.8 points
npm downloads, last week	90	15.7 points

Measured 2026-11-07. How the score works.

Where it is published

Code	ganjoor/ganjoor-mcp-server ★ 7
npm	ganjoor-mcp-server

What it can reach

Runs	On your machine
Reaches	The internet
Changes things	No: it reads only
Sign-in	None
Licence	MIT (GitHub)
Last code change	2026-10-23

Every tool sends anonymous GET-style lookups to the public Ganjoor API (api.ganjoor.net unless GANJOOR_API_BASE_URL points elsewhere); tools are annotated read-only and none change anything on Ganjoor. No key or account is used. The code runs on your machine. In HTTP mode it binds 127.0.0.1 unless HOST is set, and rejects non-loopback Origin headers unless listed in ALLOWED_ORIGINS; the docker compose file sets HOST to 0.0.0.0, exposing the port to the network. Returned poems and reader comments are third-party text.

Over time

GitHub stars 7 +0

13 Oct 20267 Nov 2026

npm downloads a week 90 +90

3000

16 Oct 20267 Nov 2026

Popularity score 27 +16 (+145 %)

3111

13 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![Ganjoor MCP Server on EveryMCPServer](https://everymcpserver.com/badge/ganjoor-mcp-server.svg)](https://everymcpserver.com/servers/ganjoor-mcp-server)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Settings 6

What it does

What it needs

Limits

Who it suits

Tools 44

Similar servers

Korean Law MCP

Karakeep MCP Server

AFFiNE MCP Server

Zotero MCP

Remnic

SiYuan MCP Server