trace-mcp

Local code graph of a repository, queried over MCP for impact, call paths and context

By Nikolai Vysotskyi (individual) TypeScript Local · stdio Developer toolsKnowledge and memory

62 popularity score ★ 202 ↓ 3.8k/wk

Connect your client

Local (npm)

Add in one click

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal
claude mcp add trace -- npx -y trace-mcp@latest serve
Claude Desktopclaude_desktop_config.json
{
  "mcpServers": {
    "trace": {
      "command": "npx",
      "args": [
        "-y",
        "trace-mcp@latest",
        "serve"
      ]
    }
  }
}
Cursor~/.cursor/mcp.json
{
  "mcpServers": {
    "trace": {
      "command": "npx",
      "args": [
        "-y",
        "trace-mcp@latest",
        "serve"
      ]
    }
  }
}
VS Code.vscode/mcp.json
{
  "servers": {
    "trace": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "trace-mcp@latest",
        "serve"
      ]
    }
  }
}
Codex~/.codex/config.toml
[mcp_servers.trace]
command = "npx"
args = ["-y", "trace-mcp@latest", "serve"]
Gemini CLITerminal
gemini mcp add --scope user trace npx -- -y trace-mcp@latest serve

Settings 6

TRACE_MCP_TELEMETRY Optional: Set to off to stop the once-a-day anonymous usage ping.
TRACE_MCP_CLIENT_PROFILE Optional: Pin or turn off (off) the per-client tool surface; auto-detected by default.
TRACE_MCP_REPO_ROOT Optional: Use this directory as the session's project root instead of the working directory.
TRACE_MCP_AUTO_REGISTER_MODE Optional: Controls implicit registration of new roots; never turns it off.
TRACE_MCP_AUTO_REGISTER_EXCLUDE Optional: Comma-separated globs of roots never to auto-register.
OPENAI_API_KEY Optional: Only when the AI provider is set to openai; ANTHROPIC_API_KEY, GEMINI_API_KEY, VOYAGE_API_KEY serve other providers.

What it does

trace-mcp parses a project once with tree-sitter and framework plugins, stores symbols, files and the edges between them in a local SQLite index, and answers an assistant's questions from that graph instead of having it open file after file. Typical questions are what depends on a symbol before it changes (get_change_impact), which code, tests and types belong to a task (get_task_context), or how a request travels from route through middleware to controller and view in frameworks such as Laravel, NestJS or Express. The same index also takes markdown vaults (Obsidian, Logseq, plain files), where notes, headings, wikilinks and tags become symbols and edges.

Beyond lookup it carries a decision log tied to code: it can mine Claude Code and Claw Code session logs for decisions by pattern matching, store them against files or symbols, and bring them back in impact results and at session start. It also has refactoring tools that edit files (rename, move, change a signature, extract a function, codemods), quality and security scans, a CI report command, and an optional Electron desktop app that shows the graph and wires up clients. Index and state live in ~/.trace/.

The tool total is larger than the README's headline: the generated tool index (last updated 23 September 2026) lists 195 registered tools, of which 163 register on every repo, 13 only when their framework is detected, and 19 only behind config flags such as topology.enabled or runtime.enabled. Five AI-backed tools (explain_symbol, suggest_tests, review_change, find_similar, explain_architecture) need ai.enabled set to true. The token-saving figures its makers publish are their own benchmarks, several marked by them as synthetic estimates.

What it needs

RuntimeNode.js 22+

Node.js 22 or newer (the package's engines field at v3.37.4 says >=22.0.0; the README does not state it). Run it inside the repository to index: the stdio server takes the project from its working directory, and `trace add` registers a project ahead of time. Semantic search runs on bundled ONNX embeddings by default; Ollama or an API key for OpenAI or another provider is needed only if you switch to them. get_diagnostics calls a type checker (tsc, mypy or pyright) that must already be installed. The desktop app is optional (macOS .dmg, Windows installer).

Limits

Each MCP session covers one project: stdio takes it from the working directory, the HTTP daemon from ?project=; queries across repositories in one session are not supported. extract_function handles TypeScript and JavaScript only. Framework tools appear only when the framework is detected, and the AI-backed tools only with ai.enabled. The --preset flag arrived after 3.11.0; older installs exit on it. On macOS `trace` clashes with Apple's /usr/bin/trace, so its makers advise keeping the `trace-mcp` command in scripts. trace init cannot write configs for Warp, JetBrains AI Assistant or the Kilo CLI 7+; those are set up by hand.

Who it suits

Suits developers using Claude Code, Cursor, Codex, Windsurf or another MCP client on medium to large codebases, especially multi-language or framework-heavy ones (Laravel with Vue/Inertia, NestJS, microservices with OpenAPI or gRPC contracts), who want impact analysis and task context served from a local index with no account. Teams that want decisions remembered against code get that in the same server. Less suited when you want a read-only server: several tools rewrite source files, and trace init by default changes client configs, hooks and CLAUDE.md. For a small single-language repo the plain file tools of the client may be enough.

Tools 60 of 195

get_project_map
Overview of detected frameworks, folder layout and entry points
search
Full-text symbol search with kind, language and path filters
search_text
Text search across the indexed files
get_symbol
Return a symbol's source by ID or qualified name
get_outline
List a file's symbols with signatures, no bodies
find_usages
Every place that imports, calls or renders a symbol or file
get_change_impact
Reverse dependencies of a file or symbol, with test reach and linked decisions
get_task_context
Code, tests and types relevant to a described task in one answer
get_feature_context
Gather code for a described feature within a token budget
get_context_bundle
Bundle a symbol with its related code for the assistant
plan_turn
Suggest a starting subgraph and past decisions for a new task
get_wake_up
Short orientation at session start, optionally resuming earlier context
get_request_flow
Follow a URL and method from route through middleware to controller
get_component_tree
Render tree of components from a root file (Vue, Nuxt, Inertia)
get_schema
Database schema rebuilt from migrations (framework-specific)
get_call_graph
Callers and callees of a function
get_type_hierarchy
Class and interface inheritance around a type
get_implementations
Classes that implement an interface
get_import_graph
Import relations between files
get_tests_for
Tests that cover a given symbol or file
get_untested_symbols
Symbols no test reaches
get_dead_code
Code nothing references
get_circular_imports
Cycles in the import graph
assess_change_risk
Risk score for a planned change
get_risk_hotspots
Files ranked by complexity, churn and coupling
get_complexity_report
Complexity figures per symbol or file
get_git_churn
How often files change in git history
compare_branches
Symbols added, changed or removed between two branches
get_changed_symbols
Symbols touched by current changes
check_quality_gates
Check complexity, coupling and security thresholds
check_architecture
Check layer rules such as clean or hexagonal presets
scan_security
Scan the code for security issues
taint_analysis
Trace untrusted input to risky sinks such as SQL or shell calls
generate_sbom
Produce a software bill of materials for the project
get_diagnostics
Run tsc, mypy or pyright and map errors to symbols
plan_refactoring
Preview a rename, move, extract or signature change without applying it
check_rename
Look for name collisions before a rename
apply_rename
Rename a symbol in its definition and every importing file
apply_move
Move a symbol or file and fix import paths
change_signature
Edit a function's parameters and update call sites
extract_function
Pull a line range into a new helper (TypeScript/JavaScript)
apply_codemod
AST-aware or regex find-and-replace across files
remove_dead_code
Delete an unreferenced symbol from its file
mine_sessions
Extract decisions from Claude Code or Claw Code session logs
add_decision
Record a decision linked to code
remember_decision
Save a decision from the running session
query_decisions
Search stored decisions by type, file, symbol, tag or date
search_sessions
Full-text search over past session content
get_subproject_impact
Which other services call a changed endpoint (opt-in)
get_service_map
Map of services and their links (opt-in)
graph_query
Query the code graph directly
traverse_graph
Walk edges outward from a node
get_pagerank
Rank symbols or files by graph centrality
visualize_graph
Open an interactive HTML dependency graph in the browser
generate_docs
Write a markdown document from the code graph
verify_docs
Check a markdown document against the code for drift
reindex
Start a full or incremental re-index
get_index_health
File, symbol and edge counts plus index errors
batch
Run several trace-mcp tools in one request
benchmark_project
Estimate token use with and without the index on this repo

Similar servers