Ganjoor MCP server

English | فارسی

Ganjoor MCP Server — the Model Context Protocol server for the Ganjoor Persian poetry API.

It lets an agent browse poets and collections, read poems with their verses, run prosody and rhyme analysis, trace reply-poems across poets, look up recitations and commentary, and explore the related-people and family-tree graphs.

44 tools, read-only access. No API key required.

Contents

• Install
• Docker
• Configuration
• Concepts
• Tool reference
• Response formats
• Usage
• Architecture
• Development
• Known limitations
• Evaluation
• Contributing

Install

Requires Node.js 18.17 or newer.

npm install ganjoor-mcp-server

VS Code

Just click the badge below to install the Ganjoor MCP server in your VS Code workspace. It will automatically add the server to your .vscode/mcp.json config.

Or add to .vscode/mcp.json:

{
  "servers": {
    "io.github.ehsanghaffar/ganjoor-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ganjoor-mcp-server"
      ],
      "env": {}
    }
  }
}

VS Code CLI:

code --add-mcp '{\"name\":\"io.github.ehsanghaffar/ganjoor-mcp-server\",\"command\":\"npx\",\"args\":[\"-y\",\"ganjoor-mcp-server\"],\"env\":{}}'

Claude Desktop / Cursor

Just click the badge below to install the Ganjoor MCP server in your Claude Desktop or Cursor app. It will automatically add the server to your MCP config.

Or add to your MCP config file:

{
  "mcpServers": {
    "io.github.ehsanghaffar/ganjoor-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ganjoor-mcp-server"
      ],
      "env": {},
      "type": "local",
      "tools": [
        "*"
      ]
    }
  }
}

Other clients

Claude Code

Use the Claude Code CLI to add the io.github.ehsanghaffar/ganjoor-mcp-server MCP server:

claude mcp add io.github.ehsanghaffar/ganjoor-mcp-server npx -y ganjoor-mcp-server

Claude Desktop

Follow the MCP install guide, use the standard config above.

Codex

Create or edit the configuration file ~/.codex/config.toml and add:

[mcp_servers.io.github.ehsanghaffar/ganjoor-mcp-server]
command = "npx"
args = ["-y", "ganjoor-mcp-server"]

For more information, see the Codex MCP documentation.

Gemini CLI

Shortened. The full README is on GitHub.