local-mcp

A lightweight, stdio-based MCP (Model Context Protocol) server for local file system operations. Designed to run as a subprocess for AI assistants (Claude, Cursor, Chatbox, etc.) that support the MCP protocol.

Features

• Read/Write/Edit files with cache (FIFO, max 10) & atomic writes (temp + rename); head+tail simultaneous reading shows start/end with omitted middle

• Search files with smart scoring (glob → grep fallback)

• Move/Rename files and directories

• List directories with iterative tree view (stack-safe, no recursion)

• Execute shell commands (bat bypass for Windows, b64 mode for complex commands)

• Batch operations with atomic rollback & $prev result referencing

• Block-level code manipulation (by function name or line range, with dry-run)

• Bookmark system for path aliases (in-memory cache, persisted to JSON)

All tool parameters include descriptions to help AI assistants call them correctly — no more guessing.

Related MCP server: Universal MCP Server

Available Tools

Installation

npm install

Usage

As an MCP server

Configure your AI assistant to spawn local-mcp as a subprocess:

{
  "mcpServers": {
    "local-mcp": {
      "command": "node",
      "args": ["path/to/local-mcp.mjs"]
    }
  }
}

Configuration via environment variables

Security

• All file operations are restricted to MCP_WORKSPACE and its subdirectories

• Shell execution writes to a temp file and immediately deletes it

• Bookmark data stored in MCP_DATA

Optimizations

Dependencies

• glob — file pattern matching

• diff — unified diff generation

Only 2 runtime dependencies, no frameworks. Total install size ~6 MB.

License

MIT