How do I use mcp-codemap?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-codemap show me an outline of the entire project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-codemap

by breca

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

mcp-codemap

Release

MCP server that gives coding agents a mental map of your codebase with progressive disclosure - like foldable code sections in an IDE, but for LLMs.

The first run parses every source file using tree-sitter and builds a graph of entities (classes, functions, interfaces, etc.) and their relationships (imports, extends, implements). This is stored in a local SQLite database (.codemap/graph.db) so subsequent sessions read from the index instantly - no re-parsing needed.

It exposes three tools. map builds the big picture - every file, class, and function at a chosen detail level, from a quick outline to full signatures with docstrings and dependency edges. query zooms into a single entity for its source code, members, and relationships without a separate file read. reindex keeps things fresh after edits, auto-detecting changes via git diff.

Supported languages:

Why

Typical exploration to understand a backend directory (44 files, ~420 entities):

Without codemap - Glob/Read/Grep or an Explore subagent:

Step	Tool calls	Chars consumed
Glob to find files	1	~500
Read models.py (572 lines)	1	~15K
Read world_service.py (628 lines)	1	~18K
Read ws.py (570 lines)	1	~15K
Read events.py (299 lines)	1	~8K
Read 4-5 API route files	4-5	~60K
Grep for cross-file imports/usage	3-5	~10K
Total	~12-15 calls	~125K+

And that's optimistic - an Explore subagent often does 15-25 tool calls across multiple turns, each with its own overhead, and still misses things.

With codemap - one or two calls:

Level	Tool calls	Chars consumed
`names` (quick orient)	1	~6K
`signatures` (working knowledge)	1	~25K

That's 5-6x fewer tokens, 12-20x fewer tool calls, and complete coverage - every entity in every file, not just the ones the agent guessed to read.

Related MCP server: Blueprint MCP

Setup

Claude Code

# npx
claude mcp add codemap -- npx mcp-codemap

# docker
claude mcp add codemap -- docker run --rm -i -v .:/project:z ghcr.io/breca/mcp-codemap

The project directory is auto-detected via MCP roots. To set it explicitly:

npx mcp-codemap serve -p /path/to/your/project

The first run indexes the project automatically. The index is stored in .codemap/graph.db inside the project directory. Subsequent calls to map or query auto-detect changed files via git diff and refresh the index before returning results — no manual reindexing needed.

Other clients

Add the MCP server config to your client's config file:

Client	Config file
Claude Code	`.mcp.json` in project root
Cursor	`.cursor/mcp.json` in project root
Crush	`.crush.json` in project root
Continue	`.continue/config.yaml`
OpenCode	`opencode.json` in project root

.mcp.json (Claude Code, Cursor):

{
  "mcpServers": {
    "codemap": {
      "command": "npx",
      "args": ["mcp-codemap"]
    }
  }
}

{
  "mcpServers": {
    "codemap": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", ".:/project:z", "ghcr.io/breca/mcp-codemap"]
    }
  }
}

.crush.json:

{
  "mcp": {
    "codemap": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-codemap"]
    }
  }
}

{
  "mcp": {
    "codemap": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", ".:/project:z", "ghcr.io/breca/mcp-codemap"]
    }
  }
}

opencode.json:

{
  "mcp": {
    "codemap": {
      "type": "local",
      "command": ["npx", "mcp-codemap"]
    }
  }
}

{
  "mcp": {
    "codemap": {
      "type": "local",
      "command": ["docker", "run", "--rm", "-i", "-v", ".:/project:z", "ghcr.io/breca/mcp-codemap"]
    }
  }
}

.continue/config.yaml:

mcpServers:
  - name: codemap
    command: npx
    args:
      - mcp-codemap

mcpServers:
  - name: codemap
    command: docker
    args:
      - run
      - --rm
      - -i
      - -v
      - .:/project:z
      - ghcr.io/breca/mcp-codemap

Tools

Response structure:

Element	Meaning
Header line	`PROJECT: <files> \| <entities> \| <languages>` - project summary
`=== dir/ [N files, M entities] ===`	Directory section with aggregate counts
`C`/`F`/`M`/`I`/`P`/`E`	Kind prefix: Class, Function, Method, Interface, Property, Enum
`:10-342`	Line range (start-end)
`exp`	Exported / public symbol
`> imports:`	Files this file imports from (resolved paths)
`> used-by:`	Files that import from this file

`map` - structural overview

Returns files, entities, signatures, and relationships as a compact text map.

map(scope?, detail?, max_depth?)

detail controls output density (default: "signatures"):

Level	Content	Relative size
`"outline"`	Files + entity counts	~1%
`"names"`	Entity names, kinds, line ranges + docstrings on top-level entities	~8%
`"signatures"`	Full signatures, docstrings, imports/used-by	~25%
`"full"`	Signatures + cross-file relationships	~40%

scope limits output to a directory or file prefix (e.g., "src/api").

Typical workflow:

map(detail="names")                          # orient on the whole project
map(scope="src/api", detail="signatures")    # drill into a module
map(detail="full")                           # inspect dependency graph

Example: `map(scope="src/tools", detail="names")`

PROJECT: 53 files | 642 entities | csharp/go/java/javascript/kotlin/php/python/ruby/rust/typescript
INDEXED: just now
C=class F=function M=method I=interface P=property E=enum V=variable T=type N=namespace

=== src/tools/ [5 files, 13 entities] ===

  src/tools/describe-entity.ts
    I DescribeEntityParams :6-9
      "Parameters for the describe-entity tool."
    F describeEntity :12-27
      "Generate or retrieve a natural-language description for a named entity."
    F formatDescribeResult :29-37

  src/tools/get-context.ts
    I GetContextParams :5-9
      "Parameters for the map tool: optional scope, depth limit, and detail level."
    F getContext :12-18
      "Build and return the compact text map of the codebase."

  src/tools/query.ts
    I QueryParams :6-8
      "Parameters for the query tool: entity name or qualified name."
    F queryEntity :11-104
      "Deep-dive on a single entity: signature, source, callers, callees, and members."

  src/tools/reindex.ts
    I ReindexParams :6-9
      "Parameters for the reindex tool: optional file paths and force flag."
    F reindex :12-52
      "Re-index changed files; auto-detects via git diff when no paths given."

  src/tools/update-context.ts
    I UpdateContextParams :6-10
      "Parameters for the update-context tool."
    F updateContext :13-55
      "Incrementally update the index; falls back to full rescan if requested."

Detail levels

outline - file list with entity counts:

PROJECT: 53 files | 642 entities | csharp/go/java/javascript/kotlin/php/python/ruby/rust/typescript
INDEXED: just now
C=class F=function M=method I=interface P=property E=enum V=variable T=type N=namespace

=== src/parser/languages/ [11 files, 162 entities] ===

  src/parser/languages/base.ts (10 entities)
  src/parser/languages/python.ts (12 entities)
  src/parser/languages/typescript.ts (10 entities)

names - adds entity names with kind prefix, line ranges, and docstrings on top-level entities:

  src/parser/languages/base.ts
    I ExtractedEntity :4-17
      "A code entity (class, function, variable, etc.) extracted from a parse tree."
    I FileParseResult :29-33
      "Complete extraction output for a single source file."
    I LanguageExtractor :45-50
      "Contract for language-specific extractors that turn parse trees into entities."
    F getDocComment :53-68
      "Extract a JSDoc-style comment immediately preceding a node."
    F getSignature :82-140
      "Build a human-readable signature string from a class, function, or interface node."

signatures - adds full signatures, docstrings, export markers, and dependency info:

  src/parser/languages/python.ts
    C class PythonExtractor implements LanguageExtractor :11-343  exp
      "Extracts classes, functions, and imports from Python source files."
      P language :12-12
      P extensions :13-13
      M extract(tree: Parser.Tree, sourceCode: string, filePath: string): FileParseResult :15-23
      M walkNode(
    node: Parser.SyntaxNode,
    sourceCode: string,
    filePath: string,
    entities: ExtractedEntity[],
    ...
  ): void :25-97
      M extractEntity(...): ExtractedEntity | null :99-171
    > imports: src/parser/languages/base.ts

  src/parser/languages/typescript.ts
    C class TypeScriptExtractor implements LanguageExtractor :15-352  exp
      "Extracts classes, functions, interfaces, and relationships from TypeScript/TSX files."
      ...
    > imports: src/parser/languages/base.ts
    > used-by: src/parser/languages/javascript.ts

full - adds a cross-file relationships section:

=== RELATIONSHIPS ===
src/parser/languages/javascript.ts -> src/parser/languages/typescript.ts [extends: TypeScriptExtractor]
src/parser/languages/python.ts -> src/parser/languages/base.ts [implements: LanguageExtractor]
src/parser/languages/typescript.ts -> src/parser/languages/base.ts [implements: LanguageExtractor]

`query` - deep dive on one entity

Returns signature, source code, callers, callees, and members for a single class, function, or method. Accepts simple or qualified names.

query(entity)

query(entity="UserService")             # find by name
query(entity="UserService.createUser")  # find by qualified name

Output includes the actual source code, so the agent doesn't need a separate file read to see the implementation.

Example output

class PythonExtractor [exported]
src/parser/languages/python.ts:10-342

SIGNATURE: class PythonExtractor implements LanguageExtractor

MEMBERS:
  property language :11-11
  property extensions :12-12
  method extract(tree, sourceCode, filePath): FileParseResult :14-22
  method walkNode(...): void :24-96
  method extractEntity(...): ExtractedEntity | null :98-170
  method extractDocstring(...): string | null :172-187

DEPENDS ON:
  imports ExtractedEntity (src/parser/languages/base.ts:3)
  imports FileParseResult (src/parser/languages/base.ts:26)
  implements LanguageExtractor (src/parser/languages/base.ts:40)

USED BY:
  imports ScanResult (src/parser/pipeline.ts:15)

SOURCE:
  10 | export class PythonExtractor implements LanguageExtractor {
  11 |   language = 'python';
  12 |   extensions = ['.py'];
  ...

Response structure:

Section	Content
Header	Entity kind, name, export status, file location
`SIGNATURE`	Full type signature
`MEMBERS`	Properties and methods with signatures and line ranges
`DEPENDS ON`	Entities this one imports, extends, or implements (with source locations)
`USED BY`	Entities that depend on this one
`SOURCE`	Full source code with line numbers

`reindex` - refresh after edits

Note: map and query automatically refresh the index before returning results, so explicit reindexing is only needed for a forced full rescan.

Re-indexes changed files. Auto-detects changes via git diff when called with no arguments.

reindex(paths?, force?)

reindex()                               # auto-detect via git diff
reindex(paths=["src/foo.ts"])           # specific files
reindex(force=true)                     # full rescan, ignore cache

Example output

Git diff update (30 changed files)
  Processed: 18
  Skipped (unchanged): 11
  Errors: 1
    src/broken.js: TypeError: Cannot read properties of undefined

Configuration

Place a config.json in the .codemap/ directory to override defaults:

{
  "excludePatterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.git/**",
    "**/vendor/**",
    "**/__pycache__/**",
    "**/target/**",
    "**/*.min.js",
    "**/*.bundle.js",
    "**/*.generated.*",
    "**/.codemap/**"
  ],
  "maxFileSize": 1000000
}

Option	Type	Default	Description
`excludePatterns`	`string[]`	See above	Glob patterns for files/directories to skip
`includePatterns`	`string[]`	`["*/.{ts,tsx,js,...,c,h,cpp,hpp,...}"]`	Glob patterns for files to include (non-git repos only)
`languages`	`string[]`	`[]` (all supported)	Restrict parsing to specific languages
`maxFileSize`	`number`	`1000000`	Skip files larger than this (bytes)
`updateGitignore`	`boolean`	`true`	Auto-add `.codemap/` to `.gitignore` on init

In git repos, file discovery uses git ls-files and respects .gitignore automatically - includePatterns is only used in non-git repos as a fallback. The exclude patterns act as a secondary filter in both cases.

CLI

The same binary works as a standalone CLI:

# npx
npx mcp-codemap map [-s scope] [--detail level]     # print the map
npx mcp-codemap query <entity>                      # inspect an entity
npx mcp-codemap reindex [paths...]                  # re-index
npx mcp-codemap stats                               # show project stats
npx mcp-codemap web [--port 3333]                   # interactive web UI
npx mcp-codemap install-hooks                       # git hooks for auto re-indexing
npx mcp-codemap uninstall-hooks                     # remove installed git hooks

# docker (mount your project at /project)
docker run --rm -v .:/project:z ghcr.io/breca/mcp-codemap map -p /project
docker run --rm -v .:/project:z ghcr.io/breca/mcp-codemap stats -p /project
docker run --rm -v .:/project:z ghcr.io/breca/mcp-codemap query <entity> -p /project
docker run --rm -v .:/project:z -p 3333:3333 ghcr.io/breca/mcp-codemap web -p /project

Web UI

codemap web launches an interactive graph explorer in your browser - a visualization of every entity and relationship in the index.

Web UI

codemap web [--port 3333]

Features:

Graph canvas - entities rendered as color-coded nodes (red = class, blue = function, purple = interface, green = enum), sized by kind, with edges drawn between them. Pan, zoom, and drag nodes to explore.
Layout modes - switch between five layouts via the top-right toolbar: Force (default), Clustered (grouped by file), Radial (most-connected at center), Columns (by directory), and Hierarchy (dependency depth top-to-bottom). Transitions are animated.
Sidebar - searchable file tree with kind filters. Type a path prefix in the exclude input to hide irrelevant directories (e.g., tests).
Detail panel - click any node or file to open a right-side panel showing its signature, file location, docstring, members, and incoming/outgoing edges. Click linked entities to navigate the graph.

Design decisions

Only path-resolved relationships (imports, extends, implements) are included in output. Name-based "calls" edges are excluded because global name lookup produces too many false positives (get, split, etc. matching unrelated symbols). See CONSTRAINTS.md for details.

Available Tools

3 tools

mapA

Returns the codebase structure as a compact map. Files, entities, signatures, and relationships in one call. Start here for orientation.

Inputs: scope, max_depth, detail.

queryA

Deep dive on a single entity. Returns signature, source code, members, resolved dependencies (imports/extends/implements), and reverse dependencies. Use after map to inspect a specific class, function, or method by name — no file path needed.

Inputs: entity (required).

reindexA

Re-index the codebase after edits. Usually unnecessary — map and query auto-refresh via git diff. Use force=true for a full rescan when the index seems stale.

Inputs: paths, force.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

A4.1/5.0

Scored 2026-06-18 02:35 across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: map provides an overview, query inspects a specific entity, and reindex refreshes the index. There is no functional overlap.

Naming Consistency4/5

All tool names are single lowercase verbs, which is consistent in style. However, they don't follow a verb_noun pattern, which is common in MCP tools, but still predictable and clear.

Tool Count5/5

With only 3 tools, the server is highly focused on codebase exploration and indexing. Each tool serves a necessary role without redundancy, making the set well-scoped.

Completeness4/5

The tools cover orientation, deep inspection, and index refreshing. Minor gaps exist, such as lacking a search tool, but the core workflows are complete for the stated purpose.

Maintenance

ActivityNo data

ResponsivenessSyncing

Resources

Related MCP Connectors

UmtriA
io.umtri
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Code Analysis Knowledge & Memory Software Architecture
321
https://mcp.umtri.io
Itamos MCP Tools
io.github.itamos-technologia
Code-map tools for AI agents: see a repo's structure first, then edit only what matters.
Code Analysis Developer Tools
11
https://mcp.itamos-technologia.com/mcp
TeamSharedC
io.github.xhad
Shared memory for coding agents. Stop re-explaining your codebase every session.
Knowledge & Memory Developer Tools
2031
https://teamshared.com/mcp
Axis Iliad - Codebase Intelligence For Agentic CommerceA
io.github.lastmanupinc-hub
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Code Analysis Developer Tools Documentation Access
4
https://api.iliad.trustfabric.ai/mcp

Related MCP Servers

OpenLore
Developer Tools Code Analysis Knowledge & Memory
clay-good
A
license
Not graded
quality
A
maintenance
Provides persistent architectural memory and structural cognition for AI coding agents, enabling efficient orientation, graph-aware context, and drift detection across codebase evolution.
Updated 3 days ago (2026-11-10 00:16 UTC)
2,916 npm
363
MIT
Blueprint MCP
Software Architecture Code Analysis Documentation Access
engincankaya
A
license
A
quality
C
maintenance
Provides AI coding agents with durable architecture memory for repositories by generating structured project maps of responsibilities, relationships, and risks.
Updated 9 days ago (2026-11-03 16:23 UTC)
6
15 npm
MIT
RepoMap
Code Analysis Developer Tools
TusharKarkera22
A
license
Not graded
quality
D
maintenance
Provides AI assistants with a structured, token-efficient map of a codebase's symbols, dependencies, and relationships via MCP tools like overview, query, and impact analysis.
Updated 7 months ago (2026-03-30 18:53 UTC)
9
MIT
mcp-code-indexer
Code Analysis Search Developer Tools
fluffypony
A
license
Not graded
quality
D
maintenance
Enables AI agents to intelligently navigate and understand codebases by providing instant file descriptions, semantic search, and context-aware recommendations, eliminating the need to repeatedly scan files.
Updated 9 months ago (2026-02-04 20:18 UTC)
89 PyPI
23
MIT

mcp-codemap

Why

Setup

Claude Code

Other clients

Tools

map - structural overview

Example: map(scope="src/tools", detail="names")

Detail levels

query - deep dive on one entity

Example output

reindex - refresh after edits

Example output

Configuration

CLI

Web UI

Design decisions

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

OpenLore

Blueprint MCP

RepoMap

mcp-code-indexer

`map` - structural overview

Example: `map(scope="src/tools", detail="names")`

`query` - deep dive on one entity

`reindex` - refresh after edits