MCP Files

You use the MCP server to access powerful code-editing capabilities from your preferred client. It lets you locate symbols across a codebase and perform surgical edits with precision, enabling faster refactoring, code exploration, and automation-friendly workflows.

How to use

Connect your MCP client to a running MCP server to start discovering symbols and applying precise edits. You can run the MCP server locally using stdio transport (direct command) or enable an HTTP transport to reach the server over a network. Use the client to search for symbols, inspect modules, and apply surgical edits like inserting or replacing exact lines in code. Typical workflows involve discovering a symbol with read_symbol, then applying exact changes with insert_text to a targeted line range.

How to install

Prerequisites: install Node.js version 20 or higher since this runtime is required for the MCP server. You also need npm or npx to run the MCP server in stdio or via the NPX-based workflow.

Step 1: Install Node.js 20+ from the official site and ensure node and npm are available in your shell.

Step 2: Choose your preferred startup method from the Quick Start options below.

Step 3: Start the MCP server using the chosen method and verify it is reachable from your MCP client.

HTTP transport options

If you want to access the MCP server over HTTP, start a local HTTP transport and point the client at the HTTP endpoint.

TRANSPORT=http PORT=3000 npx mcp-files

Configuration for HTTP or STDIO connections

HTTP connection example: configure your client to use the HTTP endpoint where the server is exposed. The endpoint URL should be the one returned by the HTTP transport start command.

Environment considerations

The MCP server supports a few environment variables to control transport, port, and debug mode. You can set these when starting the server to tailor behavior for your environment.

Troubleshooting

If you run into issues when starting or using the MCP server, verify that your Node.js version is 20 or higher and that the chosen transport (stdio or http) is correctly configured. If an import or symbol search fails, ensure the codebase is accessible and that the server process has permission to read the target files.

Notes and examples

Common workflows include discovering a symbol across the repository, then applying surgical edits to specific lines. You can use read_symbol to locate a function, and then insert_text to replace the implementation between exact line numbers. This enables precise, global refactors without unintended changes elsewhere in the codebase.

Tools and capabilities overview

The MCP server provides a suite of tools to read, inspect, search and modify code with precision. This includes symbol discovery, module inspection, and text insertion or replacement with strict line-range control.

Appendix: Quick Start options

json
{
  "mcpServers": {
    "mcp_files": {
      "command": "npx",
      "args": ["-y", "mcp-files"]
    }
  }
}

Appendix: Docker-based quick start

json
{
  "mcpServers": {
    "mcp_files_docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "flesler/mcp-files"
      ]
    }
  }
}

Appendix: HTTP transport quick start

bash
TRANSPORT=http PORT=3000 npx mcp-files

json
{
  "mcpServers": {
    "mcp_files_http": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp"
    }
  }
}

How to verify a started server

After starting the server, you should be able to connect from your MCP client and perform symbol discovery or surgical edits. If you encounter issues with the HTTP transport, check that the URL is reachable and that the port is open in your environment.

Available tools

read_symbol

Find and extract code blocks by symbol name(s) from files. Supports multiple symbols via array

import_symbol

Inspect JavaScript/TypeScript modules and their properties

search_replace

Search and replace with intelligent whitespace handling and automation-friendly multiple match resolution

insert_text

Insert or replace text at precise line ranges for surgical edits in code

os_notification

Send OS notifications using native notification systems