codeloupe-mcp

codeloupe-mcp

A Model Context Protocol (MCP) server that gives coding agents fast, local-first access to large codebases. It enables LLMs to inspect files, search text, compare directories, read symbols, and apply structured edits through bounded tool responses instead of dumping whole files or repository trees into context.

codeloupe-mcp vs shell tools

This package provides an MCP interface into repository exploration and code editing.

If you are using a coding agent, shell commands are still useful for concise build/test workflows. codeloupe-mcp is most useful when the model needs structured, repeatable, repository-aware code context across a chat session.

• Shell / CLI: best for deterministic commands such as cargo test, npm run lint, project scripts, one-off rg, and build logs that are already compact.
• MCP: best for agent loops that benefit from tool schemas, workspace-aware path resolution, bounded output, persistent indexes, and precise reads such as symbol bodies, snippets, shallow project maps, and directory diffs.

Use codeloupe-mcp when you want an agent to ask for exactly the code context it needs: a line range, a symbol body, a bounded search result, a fuzzy file match, a workspace summary, or a source-directory comparison.

Key Features

• Fast and lightweight. Local Rust server over stdio; no external indexing service, no network calls, no telemetry.
• LLM-friendly output. Tools return bounded JSON/Markdown designed for agent context windows.
• Repository-aware indexing. LMDB path metadata plus optional Tantivy content indexing per workspace.
• Precise code reads. Read focused line ranges, snippets, symbol bodies, imports, exports, call graphs, definitions, and references.
• Scoped search. Literal and regex search with path scopes, include/exclude globs, fallback diagnostics, and large-repo safeguards.
• Directory comparison. Compare two source directories with added/deleted/modified/renamed summaries and bounded diffs.
• Structured edits. Create, edit, convert, and delete files with predictable success/error metadata.

Requirements

• An MCP client that supports local stdio servers.
• Node.js 18 or newer when using npx.
• No Rust toolchain is needed when using the published npm package or a native release binary.
• Rust stable is required only when building from source.

Getting started

First, install the codeloupe-mcp server with your client.

Standard config works in most MCP clients:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

You can also use a native binary from the GitHub Releases page:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "/absolute/path/to/codeloupe-mcp",
      "args": []
    }
  }
}

On Windows native installs, point command to the .exe file, for example C:\path\to\codeloupe-mcp.exe.

<details> <summary>Amp</summary>

Add via the Amp VS Code extension settings screen or by updating your settings JSON:

"amp.mcpServers": {
  "codeloupe-mcp": {
    "command": "npx",
    "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
  }
}

Amp CLI setup:

amp mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest

</details> <details> <summary>Antigravity</summary>

Add via Antigravity settings or by updating your MCP configuration file:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

</details> <details> <summary>Claude Code</summary>

Use the Claude Code CLI:

claude mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest

Native binary alternative:

claude mcp add codeloupe-mcp -- /absolute/path/to/codeloupe-mcp

</details> <details> <summary>Claude Desktop</summary>

Follow the MCP install guide and use the standard config:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

Native Windows binary alternative:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "C:\\path\\to\\codeloupe-mcp.exe",
      "args": []
    }
  }
}

</details> <details> <summary>Cline</summary>

Follow Cline's MCP server configuration flow and add this to cline_mcp_settings.json:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "type": "stdio",
      "command": "npx",
      "timeout": 60,
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"],
      "disabled": false
    }
  }
}

</details> <details> <summary>Codex</summary>

Use the Codex CLI:

codex mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest

Alternatively, create or edit ~/.codex/config.toml:

[mcp_servers.codeloupe-mcp]
command = "npx"
args = ["-y", "@ndhkaeru/codeloupe-mcp@latest"]

</details> <details> <summary>Copilot</summary>

Use the Copilot MCP add flow, or add this to your MCP config:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "type": "local",
      "command": "npx",
      "tools": ["*"],
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

</details> <details> <summary>Cursor</summary>

Go to Cursor Settings -> MCP -> Add new MCP Server.

Use command type with:

npx -y @ndhkaeru/codeloupe-mcp@latest

Or paste the standard config:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

</details> <details> <summary>Factory</summary>

Use the Factory CLI:

droid mcp add codeloupe-mcp "npx -y @ndhkaeru/codeloupe-mcp@latest"

Alternatively, open Factory's MCP UI and paste the standard config.

</details> <details> <summary>Gemini CLI</summary>

Use the Gemini CLI MCP configuration file and add:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

</details> <details> <summary>Goose</summary>

Go to Advanced settings -> Extensions -> Add custom extension.

Use type STDIO and command:

npx -y @ndhkaeru/codeloupe-mcp@latest

</details> <details> <summary>Junie</summary>

Use Junie's MCP flow, or add to .junie/mcp/mcp.json:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

</details> <details> <summary>Kiro</summary>

Follow Kiro's MCP server documentation and add:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

</details> <details> <summary>LM Studio</summary>

Go to Program in the right sidebar -> Install -> Edit mcp.json.

Use the standard config:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

</details> <details> <summary>opencode</summary>

Add to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codeloupe-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@ndhkaeru/codeloupe-mcp@latest"],
      "enabled": true
    }
  }
}

</details> <details> <summary>Qodo Gen</summary>

Open Qodo Gen chat panel in VS Code or IntelliJ, choose Connect more tools -> + Add new MCP, then paste the standard config.

</details> <details> <summary>VS Code</summary>

Use the MCP server configuration:

{
  "servers": {
    "codeloupe-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

You can also install with the VS Code CLI:

code --add-mcp '{"name":"codeloupe-mcp","command":"npx","args":["-y","@ndhkaeru/codeloupe-mcp@latest"]}'

</details> <details> <summary>Warp</summary>

Go to Settings -> AI -> Manage MCP Servers -> + Add, or use the /add-mcp slash command and paste the standard config.

</details> <details> <summary>Windsurf</summary>

Follow Windsurf's MCP documentation and use the standard config:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

</details>

Configuration

codeloupe-mcp is configured with environment variables in the MCP server process.

| Variable | Description | |----------|-------------| | codeloupe_mcp_INDEX_DIR | Override the persistent index cache directory. | | codeloupe_mcp_TANTIVY_ENABLED | Enable/disable the Tantivy content sidecar. Defaults to true. | | codeloupe_mcp_WALK_THREADS | Filesystem walk parallelism. Values are clamped to 1..=6. | | codeloupe_mcp_BINARY | npm wrapper override for a custom local binary path. |

Example with a custom index directory:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"],
      "env": {
        "codeloupe_mcp_INDEX_DIR": "/path/to/cache"
      }
    }
  }
}

Tools

Tools are grouped by purpose. Each response uses the standard MCP content array shape and keeps output bounded for agent context.

<details> <summary>Files and edits</summary>

| Tool | Description | |------|-------------| | resolve_path | Normalize a path and return preflight accessibility metadata. | | read_file_range | Read a file or line range with encoding detection and truncation metadata. | | count_file_lines | Count lines in a text file with encoding and binary detection. | | read_snippets | Read multiple file ranges in one request. | | file_summary | Return file metadata, binary detection, and a short preview. | | convert_file_format | Rewrite a file with normalized encoding and line endings. | | create_file | Create or overwrite a file. | | create_directory | Create a directory with optional parent creation. | | edit_file | Edit a file with replace, append, prepend, or find-replace. | | delete_file | Delete one file with structured success/error metadata. |

</details> <details> <summary>Search and workspace</summary>

| Tool | Description | |------|-------------| | text_search | Literal or regex search with path scopes, include/exclude filters, and fallback diagnostics. | | fuzzy_find | Fuzzy path and file-name search across scoped roots. | | project_map | Bounded tree view with optional size metadata. | | workspace_stats | File, line, language, and size summaries. | | compare_directories | Compare two source directory trees with added/deleted/modified/renamed summaries and bounded diffs. |

</details> <details> <summary>Code intelligence</summary>

| Tool | Description | |------|-------------| | get_symbols | Extract Tree-sitter symbols from a source file. | | read_symbol_body | Read a symbol body with AST-first resolution and fallback heuristics. | | find_definition | Find likely symbol definitions across code files. | | find_references | Find likely symbol references across code files. | | list_imports | List imports for supported languages. | | list_exports | List exports for supported languages. | | get_call_graph | List outbound calls made by a function or symbol. | | compare_symbols | Compare two resolved symbols and return metadata plus a unified diff. |

</details> <details> <summary>Data and diagnostics</summary>

| Tool | Description | |------|-------------| | peek_archive | List archive entries or read one file inside an archive. | | server_health | Report uptime, workspace, and index health. | | content_index_status | Report Tantivy content-index status for scoped files or directories. | | warm_content_index | Warm Tantivy content index zones for r