Files
A comprehensive MCP server providing helpful tools for AI agents like Cursor
Install
Run one of the commands below, then pick your client in the next section.
npm
npx -y mcp-files
Setup by client
Pick your client β the config below is generated for this server (local stdio).
claude_desktop_config.json
{
"mcpServers": {
"files-flesler": {
"command": "npx",
"args": [
"-y",
"mcp-files"
]
}
}
}Format verified against the official Claude Desktop docs β.
terminal
claude mcp add files-flesler -- npx -y mcp-files
Format verified against the official Claude Code docs β.
.cursor/mcp.json
{
"mcpServers": {
"files-flesler": {
"command": "npx",
"args": [
"-y",
"mcp-files"
]
}
}
}Format verified against the official Cursor docs β.
.vscode/mcp.json
{
"servers": {
"files-flesler": {
"command": "npx",
"args": [
"-y",
"mcp-files"
]
}
}
}Format verified against the official VS Code docs β.
mcp_config.json
{
"mcpServers": {
"files-flesler": {
"command": "npx",
"args": [
"-y",
"mcp-files"
]
}
}
}Format verified against the official Windsurf docs β.
GitHub
β 10 stars Β· ζθΏζ΄ζ°δΊ 70 倩ε Β· MIT license
About this server
MCP Tools Enables agents to quickly find and edit code in a codebase with surgical precision. Find symbols, edit them everywhere. π Table of Contents π Quick Start π οΈ Available Tools β‘ Surgical Code Editing: Surgical Precision ποΈ Environment Variables π₯οΈ Server Usage π» CLI Usage ποΈ Architecture π§ͺ Development π οΈ Troubleshooting π License π Links π Quick Start Option 1: NPX (Recommended) Add this to /.cursor/mcp.json for Cursor, /.config/claude desktop config.json for Claude Desktop. Option 2: Docker Option 3: HTTP transport First run the server: Then: π οΈ Available Tools Tool Description Parameters ------ ------------- ------------ read symbol Find and extract code blocks by symbol name(s) from files. Supports multiple symbols via array symbols (string[]), file paths[]? , limit? , optimize? import symbol Import and inspect JavaScript/TypeScript modules and their properties module path , property? search replace Search and replace with intelligent whitespace handling and automation-friendly multiple match resolution file path , old string , new string , allow multiple matches? insert text Insert/replace text at precise line ranges. Perfect for direct line operations from code citations (12:15:file.ts) and surgical edits in large files file path , from line , text , to line os notification Send OS notifications using native notification systems message , title? β‘ Surgical Code Editing: Surgical Precision The combination of read symbol + insert text unlocks revolutionary code editing capabilities that transform how AI agents work with codebases. π― The Power Combo Symbol Discovery ( read symbol ) - Find ANY symbol(s) ANYWHERE in your codebase: Surgical Editing ( insert text ) - Make precise modifications using exact line ranges: π Superpowers Unlocked π Cross-Codebase Intelligence Find any symbol across entire repositories instantly No manual searching through files and folders Perfect accuracy even in massive codebases βοΈ Precision Surgery Edit exact functions, classes, or code blocks Replace implementations without affecting surrounding code Insert enhancements at perfect locations ποΈ Zero-Error Refactoring Update function signatures everywhere they exist Modify APIs across all files simultaneously Fix bugs with surgical precision across entire codebase π‘ Real-World Magic This transforms AI from "helpful assistant" to "surgical code surgeon" π¦Ύ ποΈ Environment Variables Variable Default Description ---------- --------- ------------- TRANSPORT stdio Transport mode: stdio or http PORT 4657 HTTP server port (when TRANSPORT=http ) DEBUG false Enable debug mode and utils debug tool π₯οΈ Server Usage You can either install and use mcp-files or npx mcp-files . π» CLI Usage All tools can be used directly from the command line: ποΈ Architecture Type-safe tools with Zod validation Self-contained modules in src/tools/ Cross-platform support (Linux, macOS, Windows, WSL) Performance optimized with memoization Clear error handling with descriptive messages π§ͺ Development π§Ή Code Optimization The read symbol tool includes an optimize parameter that cleans up code for AI processing: What it does: Strips comments : Removes // , / / , and / / comments Collapses newlines : Multiple consecutive newlines become single newlines Normalizes indentation : Converts spaces to tabs (detects indentation token size automatically) Removes base indentation : Eliminates common leading whitespace Usage: Perfect for: Reducing token count in AI context windows while preserving code structure and readability. π οΈ Troubleshooting Requirements Node.js β₯20 - This package requires Node.js version 20 or higher Common Issues ERR MODULE NOT FOUND when running npx mcp-files Problem : Error like Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js' when running npx mcp-files Cause : Corrupt or incomplete npx cache preventing proper dependency resolution Solution : Clear the npx cache and try again: Note : This issue can occur on both Node.js v20 and v22, and the cache clear resolves it Tools not showing up in MCP client: Verify Node.js version is 20 or higher Try restarting your MCP client after configuration changes File operations failing: Ensure proper file permissions for the files you're trying to read/modify Use absolute paths when possible for better reliability Check that the target files exist and are accessible π License MIT - see LICENSE file. π Links π¦ NPM Package π GitHub Repository π Report Issues π MCP Specification --- Built for AI agents π€β¦
Summary from the project README β github.com/flesler/mcp-files
Distributed as stdio, listed under Files & Storage. Review our MCP security guide before granting access to real data.
Frequently asked questions
What does the Files MCP server do?
MCP Tools Enables agents to quickly find and edit code in a codebase with surgical precision. Find symbols, edit them everywhere. π Table of Contents π Quick Start π οΈ Available Tools β‘ Surgical Code Editing: Surgical Precision ποΈ Environment Variables π₯οΈ Server Usage π» CLI Usage ποΈ Architecture π§ͺ Development π οΈ Troubleshooting π License π Links π Quick Start Option 1: NPX (Recommended) Add this to /.cursor/mcp.json for Cursor, /.config/claude desktop config.json for Claude Desktop. Option 2: Docker Option 3: HTTP transport First run the server: Then: π οΈ Available Tools Tool Description Parameters ------ ------------- ------------ read symbol Find and extract code blocks by symbol name(s) from files. Supports multiple symbols via array symbols (string[]), file paths[]? , limit? , optimize? import symbol Import and inspect JavaScript/TypeScript modules and their properties module path , property? search replace Search and replace with intelligent whitespace handling and automation-friendly multiple match resolution file path , old string , new string , allow multiple matches? insert text Insert/replace text at precise line ranges. Perfect for direct line operations from code citations (12:15:file.ts) and surgical edits in large files file path , from line , text , to line os notification Send OS notifications using native notification systems message , title? β‘ Surgical Code Editing: Surgical Precision The combination of read symbol + insert text unlocks revolutionary code editing capabilities that transform how AI agents work with codebases. π― The Power Combo Symbol Discovery ( read symbol ) - Find ANY symbol(s) ANYWHERE in your codebase: Surgical Editing ( insert text ) - Make precise modifications using exact line ranges: π Superpowers Unlocked π Cross-Codebase Intelligence Find any symbol across entire repositories instantly No manual searching through files and folders Perfect accuracy even in massive codebases βοΈ Precision Surgery Edit exact functions, classes, or code blocks Replace implementations without affecting surrounding code Insert enhancements at perfect locations ποΈ Zero-Error Refactoring Update function signatures everywhere they exist Modify APIs across all files simultaneously Fix bugs with surgical precision across entire codebase π‘ Real-World Magic This transforms AI from "helpful assistant" to "surgical code surgeon" π¦Ύ ποΈ Environment Variables Variable Default Description ---------- --------- ------------- TRANSPORT stdio Transport mode: stdio or http PORT 4657 HTTP server port (when TRANSPORT=http ) DEBUG false Enable debug mode and utils debug tool π₯οΈ Server Usage You can either install and use mcp-files or npx mcp-files . π» CLI Usage All tools can be used directly from the command line: ποΈ Architecture Type-safe tools with Zod validation Self-contained modules in src/tools/ Cross-platform support (Linux, macOS, Windows, WSL) Performance optimized with memoization Clear error handling with descriptive messages π§ͺ Development π§Ή Code Optimization The read symbol tool includes an optimize parameter that cleans up code for AI processing: What it does: Strips comments : Removes // , / / , and / / comments Collapses newlines : Multiple consecutive newlines become single newlines Normalizes indentation : Converts spaces to tabs (detects indentation token size automatically) Removes base indentation : Eliminates common leading whitespace Usage: Perfect for: Reducing token count in AI context windows while preserving code structure and readability. π οΈ Troubleshooting Requirements Node.js β₯20 - This package requires Node.js version 20 or higher Common Issues ERR MODULE NOT FOUND when running npx mcp-files Problem : Error like Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js' when running npx mcp-files Cause : Corrupt or incomplete npx cache preventing proper dependency resolution Solution : Clear the npx cache and try again: Note : This issue can occur on both Node.js v20 and v22, and the cache clear resolves it Tools not showing up in MCP client: Verify Node.js version is 20 or higher Try restarting your MCP client after configuration changes File operations failing: Ensure proper file permissions for the files you're trying to read/modify Use absolute paths when possible for better reliability Check that the target files exist and are accessible π License MIT - see LICENSE file. π Links π¦ NPM Package π GitHub Repository π Report Issues π MCP Specification --- Built for AI agents π€
How do I install Files?
Run the install command shown above, then paste the config for your client (Claude Desktop, Claude Code, Cursor, VS Code or Windsurf) into its MCP settings and restart the client.
Is Files free to use?
The MCP server itself is free to install. The source is public on https://github.com/flesler/mcp-files. Any third-party service it calls may require its own API key and account.
Which clients support Files?
Any MCP-compatible client can use it, including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and custom agents.
Add this badge
Publish this server? Link back with a badge on your README or site β copy either snippet.
Markdown
[](https://mcpnav.net/server/files-flesler/)
HTML
<a href="https://mcpnav.net/server/files-flesler/"><img src="https://mcpnav.net/badge/files-flesler.svg" alt="Listed on MCPNav" height="20"></a>