KIRI MCP Server

Intelligent code context extraction for LLMs via Model Context Protocol

KIRI is an MCP server that provides intelligent code context extraction from Git repositories. It indexes your codebase into DuckDB and exposes semantic search tools for LLMs.

Why KIRI?

• MCP Native: Plug-and-play with Claude Desktop, Codex CLI, and other MCP clients
• Smart Context: Extract minimal, relevant code fragments based on task goals
• Accurate: MRR 1.0 — the most relevant file always ranks first
• Fast: Sub-second response time for most queries
• Semantic Search: Multi-word queries, dependency analysis, BM25 ranking
• Auto-Sync: Watch mode automatically re-indexes on file changes
• Phrase-Aware: Recognizes compound terms (kebab-case, snake_case)

Quick Start

1. Install

npm install -g kiri-mcp-server

Or use npx without installation.

2. Configure Claude Code

Edit ~/.claude/mcp.json:

{
  "mcpServers": {
    "kiri": {
      "command": "kiri",
      "args": ["--repo", ".", "--db", ".kiri/index.duckdb", "--watch"]
    }
  }
}

3. Restart Claude Code

KIRI automatically indexes your repository on first startup.

Other MCP clients: See Setup Guide for Codex CLI and other configurations.

MCP Tools

| Tool | Purpose | Example | | ----------------- | ----------------------------- | -------------------------------- | | context_bundle | Find relevant code for a task | goal: "auth token refresh bug" | | files_search | Search files by keywords | query: "handler" | | snippets_get | Read specific code sections | path: "src/server/handlers.ts" | | deps_closure | Analyze dependencies | direction: "inbound" | | semantic_rerank | Refine search results | candidates: [...] |

Full documentation: Tools Reference

Supported Languages

| Language | Extensions | Parser | | ---------- | ------------- | ----------------------- | | TypeScript | .ts, .tsx | TypeScript Compiler API | | Swift | .swift | tree-sitter-swift | | PHP | .php | tree-sitter-php | | Java | .java | tree-sitter-java | | Dart | .dart | Dart Analysis Server | | Rust | .rs | tree-sitter-rust |

Other languages are indexed but use full-file snippets instead of symbol extraction.

Troubleshooting

Database Issues

# Delete and rebuild
rm -rf .kiri/
# Restart MCP client - KIRI will automatically reindex

Daemon Timeout (Large Repositories)

{
  "env": { "KIRI_DAEMON_READY_TIMEOUT": "480" }
}

Stale Lock File

rm -f .kiri/index.duckdb.sock.lock

Version Mismatch After Upgrade

pkill -f "kiri.*daemon"

More issues: See full troubleshooting guide below.

For Developers

git clone https://github.com/CAPHTECH/kiri.git
cd kiri
pnpm install
pnpm run build
pnpm run test
pnpm run dev  # HTTP server on :8765

Guidelines: See AGENTS.md for development standards.

Documentation

| Document | Description | | ------------------------------------------------------ | ------------------------------------------- | | Setup Guide | Installation and MCP client configuration | | Tools Reference | Complete MCP tools documentation | | Configuration | Environment variables and advanced settings | | Architecture | System design and data flow | | Data Model | Database schema details | | Search & Ranking | Search algorithms | | API Reference | Complete API documentation | | Authoring Docs | Writing metadata-rich documentation |

Changelog

See CHANGELOG.md for release notes.

Recent highlights:

• v0.25.6: Fix daemon startup deadlock from v0.25.5
• v0.25.4: snippets_get content size handling improvements
• v0.25.3: Query language guidance in MCP tool descriptions (PR #182)
• v0.25.2: Auto reindex on DeserializeDeletes IO corruption (PR #181)

Detailed Troubleshooting

Daemon Initialization Timeout

Problem: "Daemon did not become ready within X seconds"

Solutions:

1. Increase timeout (Claude Code: KIRI_DAEMON_READY_TIMEOUT=480, Codex CLI: startup_timeout_sec = 480)
2. Check logs: cat .kiri/index.duckdb.daemon.log
3. Manual test: kiri --repo . --db .kiri/index.duckdb --port 8765

Command Not Found

# Verify installation
npm list -g kiri-mcp-server

# Re-link
npm link kiri-mcp-server

# Or use npx
npx kiri-mcp-server@latest --repo . --db .kiri/index.duckdb

Slow Indexing

1. Check size: git ls-files | wc -l
2. Review .gitignore
3. Add denylist: Create .kiri/denylist.yml:

patterns:
  - "**/*.min.js"
  - "**/vendor/**"

DuckDB Native Binding Errors

# Use pnpm link, not npm link
rm -rf node_modules pnpm-lock.yaml
pnpm install --frozen-lockfile
pnpm rebuild duckdb
pnpm run build
pnpm link --global

Schema Mismatch (Degrade Mode)

pkill -f "kiri.*daemon"
rm -f .kiri/index.duckdb.sock.lock .kiri/index.duckdb.sock
kiri --repo . --db .kiri/index.duckdb --full

Getting Help

1. Check logs: .kiri/index.duckdb.daemon.log
2. Enable debug: DEBUG=kiri:*
3. GitHub Issues
4. Discussions

License

MIT License - See LICENSE.

Acknowledgments

Built with Model Context Protocol, DuckDB, and tree-sitter.

Status: v0.25.6 (Beta) - Production-ready for MCP clients