orgraph-mcp

Codebase knowledge graph for coding agents. Gives Claude Code, Cursor, Codex, and other MCP-compatible agents a persistent graph of any repo — call chains, topology clusters, dependency trees — on top of hybrid code search.

Quickstart

Install uv, then:

uv tool install orgraph-mcp
orgraph install

orgraph install detects installed coding agents and wires up the MCP server automatically. Open any repo in your agent and orgraph starts working — it indexes on first run, no manual setup needed.

To undo: orgraph uninstall

What agents can do

Once configured, your agent has 6 tools:

Tool What it does
search(query) Hybrid BM25+semantic search — find code by description
trace(symbol, direction, depth) Follow call chains forward (callees) or backward (callers)
get_context(file_or_symbol) Topology cluster, community, call depth, indegree — where does this fit?
find_entry_points(kind) HTTP handlers and entry surfaces; kind = "all" | "http" | "topology"
get_dependencies(file, direction, depth) Import + call dependency tree, forward or reverse
reindex(force) Re-index changed/deleted files without restarting the server

The agent picks the right tool automatically based on what you ask.

Manual usage

# Index a repo manually (optional — serve auto-indexes)
orgraph index /path/to/repo

# Check what was indexed
orgraph status /path/to/repo

# Search from the CLI
orgraph search "authentication middleware" /path/to/repo

# Start the MCP server
orgraph serve /path/to/repo

Manual MCP config

If you prefer to configure manually instead of using orgraph install:

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "orgraph": {
      "command": "uvx",
      "args": ["--from", "orgraph-mcp", "orgraph", "serve", "."],
      "type": "stdio"
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "orgraph": {
      "command": "uvx",
      "args": ["--python", "3.13", "--from", "orgraph-mcp", "orgraph", "serve", "."]
    }
  }
}

The server uses . as the repo path — it starts relative to wherever your agent opens the project.

How it works

  • Extraction — tree-sitter AST extractor (SCIP compiler-accurate extraction when available)
  • Graph — Kuzu embedded graph DB with Function/Class/File nodes + CALLS/IMPORTS/INHERITS edges
  • Search — semble hybrid BM25 + Model2Vec embeddings
  • Topology — BFS entry-point clustering groups files into domain clusters
  • Communities — Leiden community detection for finer-grained groupings
  • Incremental — md5 manifest tracks changes; reindex only re-extracts what changed

Eval

Measure retrieval quality against a ground truth file:

orgraph eval /path/to/repo --ground-truth queries.json --output report.json

Ground truth format:

[
  {
    "id": "auth-flow",
    "query": "how is authentication handled",
    "relevant_files": ["auth.py", "middleware.py"],
    "relevant_symbols": ["authenticate", "require_auth"],
    "query_type": "semantic"
  }
]

Reports NDCG@10, MRR, and Precision@3.

Project links

Data verified by PyPI on Jun 18, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.34)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for pranawww from gravatar.com pranawww

Credits

Author: Pranav Kumar

GitHub Statistics

Data verified by PyPI on Jun 18, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python <3.14, >=3.11

Provides Extra

dev

Tags

agents code-search codebase knowledge-graph llm mcp

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

orgraph_mcp-0.1.30.tar.gz (306.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

orgraph_mcp-0.1.30-py3-none-any.whl (208.1 kB view details)

Uploaded Python 3

File details

Details for the file orgraph_mcp-0.1.30.tar.gz.

File metadata

  • Download URL: orgraph_mcp-0.1.30.tar.gz
  • Upload date:
  • Size: 306.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for orgraph_mcp-0.1.30.tar.gz
Algorithm Hash digest
SHA256 7dbae46bfa31af02addd24a8945ce1fbec9179f391beb8ad3394284849f78a86
MD5 b1d1bda2a71851e7442237acb4ba7690
BLAKE2b-256 413344c6336ab2f8c0099dd85fd27746419afdc4118aa633417b6de9ab1a3748

See more details on using hashes here.

Provenance

The following attestation bundles were made for orgraph_mcp-0.1.30.tar.gz:

Publisher: release.yml on tss-pranavkumar/orgraph

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file orgraph_mcp-0.1.30-py3-none-any.whl.

File metadata

  • Download URL: orgraph_mcp-0.1.30-py3-none-any.whl
  • Upload date:
  • Size: 208.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for orgraph_mcp-0.1.30-py3-none-any.whl
Algorithm Hash digest
SHA256 965e7f33121409d38b83e146d685c4e35bed9e55dd08b42e27a9d051cbf019c1
MD5 439ffc641e2316406b5019dc958f51ab
BLAKE2b-256 977004fb93e538e152f5034508355405524d4857e76a787b4689cf7e5db05a9c

See more details on using hashes here.

Provenance

The following attestation bundles were made for orgraph_mcp-0.1.30-py3-none-any.whl:

Publisher: release.yml on tss-pranavkumar/orgraph

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page