Tripitaka MCP

Tripitaka MCP Server

An MCP server for searching and citing content from the Pāli Tipiṭaka. It lets AI clients such as Claude or Cursor look up suttas, quote the teachings, and compare translations across languages.

🙏 This project is offered as Dhamma Dāna: 100% free, non-commercial only.

License details: LICENSE (code) and NOTICE.md (data)

✨ Features

• Full Tipiṭaka coverage, at parity with SuttaCentral. All three baskets are indexed, about 444K segments. Sutta carries Pāli plus English from bilara-data's translators (Bhikkhu Sujato for DN/MN/SN/AN and most of the Khuddaka Nikāya, with John Kelly, Bhikkhu Kovilo and others for a few KN books). Vinaya carries Pāli plus Bhikkhu Brahmali's English. Abhidhamma is Pāli only, because upstream bilara-data has no English for any Abhidhamma book. list_structure reports live counts.
• Hybrid search merges keyword and semantic results through Reciprocal Rank Fusion (RRF). It is the most precise of the search tools and needs no configuration.
• Keyword search with trigram fuzzy matching and cross-language alignment.
• Semantic search by meaning, using vector similarity (pgvector).
• Translation comparison across editions, aligned segment by segment.
• Dictionary bridge with 20,000+ entries (P. A. Payutto, PTS, DPPN).
• Sutta fetch and citations. Get a sutta by ID (mn1, pli-tv-bu-vb-pj1, patthana1.1) and generate a properly formatted academic citation.
• Pāli word analyzer that strips inflectional suffixes to find the root form when a dictionary lookup misses (bhikkhūnaṁ → bhikkhu).
• Cross-reference URLs in every response: a clickable deep link into the project's own bilingual reader (Pāli + English, with a segment anchor that highlights the cited verse). The reader renders SuttaCentral's bilara-data verbatim, so it is the authoritative text, and AI clients surface the link so users can verify the source in one click.
• Dual transport: legacy SSE (/sse) and canonical Streamable HTTP (/mcp, MCP spec 2025-03-26).
• MCP resources: tripitaka://structure, tripitaka://sutta/{id}, tripitaka://word/{w}, for clients that pin context as resources.
• Curated reference pages at /topics/*: six markdown pages covering canon structure, getting started and tool selection, places (Mahājanapada, holy sites, cosmology), 10 foundational themes with locus classicus, about 30 major figures, and a phase-based timeline of the Buddha's 45-year mission. Sutta IDs are verified against live data, and an AI client can fetch one page instead of running 30+ tool calls.
• Claude skill. skills/tipitaka-research.md is a ready-to-install workflow file that turns on a multi-step research pattern (clarify → verify coverage → search → drill in → cite) on Claude Desktop and Claude Code.
• Postman collection included for testing the API.

🏗️ Tech stack

🚀 Quick start

🌐 No setup: connect to the public Dhamma Dāna server

The maintainers run a free public instance at tripitaka-mcp.com.

Connecting Claude Desktop takes three steps. Nothing to install but Node.js, and no Docker or GPU.

1. Find your absolute npx path. Claude Desktop doesn't read your shell profile, so a bare npx won't resolve. Open a terminal:

which npx

example: /Users/you/.nvm/versions/node/v22.14.0/bin/npx

2. Open claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows) and add the entry below. Substitute YOUR_NPX_PATH with the output from step 1, and YOUR_NODE_BIN_DIR with that path's parent directory:

{

"mcpServers": { "tripitaka": { "command": "YOUR_NPX_PATH", "args": ["-y", "mcp-remote", "https://mcp.tripitaka-mcp.com/mcp"], "env": { "PATH": "YOUR_NODE_BIN_DIR:/usr/local/bin:/usr/bin:/bin" } } } }

3. Quit Claude Desktop completely (⌘Q on macOS, tray → Quit on Windows) and reopen. The 🔌 indicator in the bottom-left should show tripitaka with 14 tools available.

_The first connection takes 5 to 10 seconds_ while npx downloads mcp-remote on demand. Give Claude Desktop a moment after the restart before deciding it failed.

Once connected, try asking Claude things like:

• "What does the Buddha teach about mindfulness of breathing? Quote the relevant passages from MN 118."
• "Show me the full text of the Karaṇīyamettasutta in Pāli and English."
• "What does the Pāli word _sati_ mean according to the Payutto dictionary?"
• "Find suttas where the Buddha discusses anger."

Claude will pick the right tool, fetch the canonical Pāli, and surface a clickable link to the project's bilingual reader for verification.

The hosted server is a small free service offered for personal study, research, and dhamma practice. Keep your request rate reasonable; bursts may be throttled at the edge. Read NOTICE.md before redistributing it or using it commercially.

💻 Run it fully offline (pipx, local SQLite, no server)

If you would rather keep everything on your own machine, with no network calls to the hosted server, install the local edition. It carries the whole Pāli canon as a single SQLite file (~120 MB) and runs as a local stdio MCP server.

pipx install tripitaka-mcp     # needs Python 3.10+

tripitaka-mcp init # one-time: downloads the SQLite database tripitaka-mcp serve # runs the MCP server over stdio

If the install fails like this:

Because the current Python version (3.9.6) does not satisfy Python>=3.10

pipx is using a different interpreter than you think. It builds its own isolated environment on purpose and ignores whatever venv you have active, so an old system Python gets picked even when the shell you typed in has 3.12. Tell it which to use:

pipx install --python python3.12 tripitaka-mcp

(Any 3.10 or newer works; pipx environment shows what it defaults to.)

Then point Claude Desktop or Cursor at the local command, with no npx bridge and no internet:

{

"mcpServers": { "tripitaka": { "command": "tripitaka-mcp", "args": ["serve"] } } }

(If tripitaka-mcp isn't on the client's PATH, use the absolute path from which tripitaka-mcp.)

Need a URL instead of stdio? Scripts, notebooks, and anything that shares one server across several clients want an HTTP endpoint rather than a subprocess:

tripitaka-mcp serve --http                 # http://127.0.0.1:8765/mcp

tripitaka-mcp serve --http --port 9000 # or MCP_HOST / MCP_PORT

It binds 127.0.0.1 unless you say otherwise; the canon is read-only, but nothing here asks who is calling, so think before binding a public interface.

Hosted vs local

Both serve the same ~444K-segment canon. The differences:

search_semantic, search_hybrid, and the trigram keyword index need PostgreSQL, pgvector, and a ~1 GB embedding model, which is more than a lightweight local install should carry, so they stay hosted-only. In local mode those two tools are never registered: a connected client sees only the 11 it can actually call.

Because the local server is a standard stdio MCP server, it also gives you a fully offline AI stack. Pair it with a local model such as Ollama and any MCP-capable chat UI, and nothing leaves your machine.

🏎️ Fastest local path: the installer (recommended for non-developers)

git clone https://github.com/dhamma-seeker/tripitaka-mcp.git

cd tripitaka-mcp ./scripts/install.sh

The installer downloads a prepared database dump from Hugging Face (dhamma-seeker/tripitaka-mcp-dump) and restores it for you, which brings setup down from two to four hours (loading the data, then generating embeddings) to about five minutes. (If a dump file is already on disk, the installer uses that copy instead.)

The installer will:

1. Verify that docker, compose, openssl, and curl are installed
2. Generate .env with random passwords (for both the admin and the readonly user)
3. Download the dump from Hugging Face (if not already local)
4. Start the DB and restore the dump
5. Set up the readonly role and runtime timeouts
6. Print a ready-to-paste Claude Desktop config

Options:

./scripts/install.sh --dump PATH          # use an existing dump file

./scripts/install.sh --dump-url URL # override the dump source ./scripts/install.sh --no-dump # skip restore (load data yourself later)

---

🔧 Manual setup (for developers)

1. Clone & setup

git clone https://github.com/dhamma-seeker/tripitaka-mcp.git

cd tripitaka-mcp cp .env.example .env

Set POSTGRES_PASSWORD in .env to a random password

2. Start database

docker compose up db -d

3. Install dependencies

python -m venv .venv

source .venv/bin/activate pip install -r requirements.txt

4. Initialize database & load data

# 1. Seed metadata (pitaka, nikāya)

python scripts/seed_metadata.py

2. Download & load Sutta Piṭaka data from SuttaCentral

python scripts/data_loader.py

3. Load Thai CC0 translations (Dhīranando & Jayasāro)

python scripts/load_thai_cc0.py

4. Load dictionaries (DPD, PTS, DPPN, and the Payutto dictionary)

python scripts/load_dictionary.py

5. Generate embeddings for semantic / hybrid search

python scripts/generate_embeddings.py

5. Run MCP server

python main.py