# codeloupe-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/ndhkaeru/codeloupe-mcp  
**GitHub Stars:** 4  
**npm Downloads (last month):** 724  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/codeloupe-mcp

## Description
Local-first MCP server for code search, repository intelligence, comparison, and safe file edits.

## Tools
Capabilities this server exposes over MCP:

- **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.
- **file_hash** — Compute a file's SHA-256 digest with streaming I/O.
- **validate_json** — Validate JSON syntax from a UTF-8 file or inline content.
- **convert_file_format** — Rewrite a file with normalized encoding and line endings.
- **create_file** — Create or overwrite a file, with an optional overwrite hash precondition.
- **copy_file** — Stream and verify a byte-for-byte file copy without overwriting.
- **move_file** — Move or rename one file, including verified cross-device moves and inverse-move undo.
- **diff_files** — Compare text paths, inline content, or retained before/after history snapshots.
- **create_directory** — Create a directory with optional parent creation.
- **edit_file** — Edit a file with replace, append, prepend, or find-replace.
- **edit_files** — Preview or apply exact edits or ordered file operations with virtual preflight, rollback, and grouped undo.
- **delete_file** — Delete one file with structured success/error metadata.
- **list_history** — List metadata for recent process-local write snapshots without returning file contents.
- **undo_change** — Restore one `entry_id` or a complete `change_set_id` after checking every affected path.
- **search_workspace** — Run path, symbol-definition, and exact text searches concurrently with grouped engine status.
- **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 inventory-first summaries and optional bounded diffs.
- **workspace_index** — Estimate, enable, or disable indexing for one workspace without bypassing server safety budgets.
- **get_symbols** — Extract Tree-sitter symbols, qualified names, and declaration lines from a source file.
- **read_symbol_body** — Resolve qualified or unqualified symbols with AST-first resolution and fallback heuristics.
- **find_definition** — Find case-sensitive qualified or unqualified definitions with AST-first resolution and labeled heuristic fallback.
- **find_references** — Find token matches and classify AST-supported results as code, comment, or string.
- **list_imports** — List imports for supported languages.
- **list_exports** — List exports for supported languages.
- **get_call_graph** — List outbound calls made by a qualified or unqualified function or method.
- **compare_symbols** — Compare two unambiguous resolved symbols and return compact metadata plus a unified diff.
- **peek_archive** — List up to 1,000 archive entries or read one inner file up to 10 MiB.
- **server_health** — Report uptime, workspace, and index health.
- **index_gc** — Inspect persistent index storage and optionally delete selected stale/orphaned indexes.
- **content_index_status** — Report Tantivy content-index status for scoped files or directories.
- **warm_content_index** — Warm Tantivy content index zones for repeated searches.
- **batch_tool_call** — Run up to 20 ordered tools with a shared deadline, cancellation, fair output budgets, and bounded per-call results.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/codeloupe-mcp/readme_