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.27.tar.gz (294.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.27-py3-none-any.whl (202.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: orgraph_mcp-0.1.27.tar.gz
  • Upload date:
  • Size: 294.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.27.tar.gz
Algorithm Hash digest
SHA256 b7a963eee846ef7b60e2e2dc71a49785bc38fe40745c9604ddb1e8ff56f5478a
MD5 c9faf47cae6b240200e0b67626b994ab
BLAKE2b-256 15943e1e924bf757e20d5cdaea5e29129f8785dfa0362afa1101115f22dbe6a8

See more details on using hashes here.

Provenance

The following attestation bundles were made for orgraph_mcp-0.1.27.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.27-py3-none-any.whl.

File metadata

  • Download URL: orgraph_mcp-0.1.27-py3-none-any.whl
  • Upload date:
  • Size: 202.8 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.27-py3-none-any.whl
Algorithm Hash digest
SHA256 42bbf992dfc5915801d625dd6e3577b4519bd093612e117492240a8fe2e095e3
MD5 8b2fcb540551d4a74a434d06b990fc89
BLAKE2b-256 3eea8ac83a932e64cea8a7cded547390fce28997f7f2448b95faf293c944160b

See more details on using hashes here.

Provenance

The following attestation bundles were made for orgraph_mcp-0.1.27-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