Codeloupe MCP

What codeloupe-mcp MCP server does

The codeloupe-mcp MCP server exposes local repository exploration and editing through MCP tool calls. It is designed for coding-agent workflows where the model needs a bounded answer: a selected line range, a matching snippet, a symbol body, a workspace summary, or a comparison between source directories. Results are returned as constrained JSON or Markdown instead of requiring an entire file or tree to be placed in context.

The server can inspect files, search literal text or regular expressions, resolve symbols and related code, compare directories, and perform structured file changes. Its repository-aware behavior helps repeated requests work from workspace paths and indexes rather than treating every request as an unrelated shell command.

How it works

codeloupe-mcp runs locally over stdio. The published npm package can be launched with npx, and a native executable is also available through GitHub Releases. No external indexing service, network connection, or telemetry is required according to the project documentation.

Workspace metadata is stored in LMDB, while optional content indexing uses Tantivy for each workspace. Search supports path scopes and include or exclude globs, with fallback diagnostics and safeguards for large repositories. Directory comparisons can summarize added, deleted, modified, and renamed items with bounded diffs.

The server complements rather than replaces shell tools. Use shell commands for deterministic build, test, lint, project-script, or compact log tasks; use codeloupe-mcp when the agent benefits from schemas, workspace-aware paths, bounded output, persistent indexes, and targeted code reads.

Setup and configuration

An MCP client that supports local stdio servers is required. With npx, use Node.js 18 or newer. The published package and native release do not require a Rust toolchain. Building from source requires Rust 1.98.1, with the repository's toolchain file selecting the pinned version through rustup.

A standard client configuration runs npx -y @ndhkaeru/codeloupe-mcp@latest. Alternatively, configure the absolute path to the native binary; on Windows, use the .exe path. The project documents setup examples for Claude Desktop, Claude Code, Cline, Codex, Cursor, Gemini CLI, LM Studio, VS Code, Windsurf, and other MCP clients.

The codeloupe-mcp MCP server accepts repeatable --workspace <path> or --workspace=<path> arguments. Workspace paths supplied through the command line or environment are approved for indexing unless index mode is disabled. --help and --version exit before the stdio server starts, and unknown command-line options produce an error.

Tools and capabilities

• Inspect files and read bounded line ranges or snippets.
• Read symbol bodies, imports, exports, definitions, references, and call graphs.
• Search literal text or regular expressions within scoped paths.
• Match files fuzzily and produce workspace summaries.
• Compare source directories with bounded change summaries and diffs.
• Create, edit, convert, delete, batch-edit, and undo files with success or error metadata.

Limitations and notes

The server is intended for local stdio use and requires an MCP client with that capability. It is not a replacement for shell-based build, test, or lint workflows. Output is intentionally bounded, so requests return focused context rather than unrestricted repository contents. The documentation also describes large-repository safeguards and optional indexing behavior, so index availability depends on the configured mode and workspace setup.