Files
Enables AI agents to safely explore directories, read files, search content by pattern or filename, and edit files with checksum verification and dry-run preview within sandboxed filesystem access.
What is Files?
Files is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to enables ai agents to safely explore directories, read files, search content by pattern or filename, and edit files with checksum verification and dry-run preview within sandboxed filesystem access.
Enables AI agents to safely explore directories, read files, search content by pattern or filename, and edit files with checksum verification and dry-run preview within sandboxed filesystem access.
This server falls under the File Systems category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Enables AI agents to safely explore directories, read files,
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx files-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Files
Files MCP Server gives AI agents sandboxed access to your local filesystem, exposing four core tools for browsing directories, reading files, searching content by pattern or filename, and making verified file edits. It enforces safety through configurable root directory restrictions (FS_ROOTS), mandatory checksum verification before writes, and a dry-run mode that previews changes as a unified diff before applying them. Developers use it to let AI assistants explore codebases, find and refactor files, and automate file management tasks — all within a well-defined, auditable boundary.
Prerequisites
- Bun runtime installed (bun.sh) for running the server from source
- Node.js 18+ if using npx instead of bun
- An MCP-compatible client such as Claude Desktop or Cursor
- Local directories you want to expose to the AI agent
Clone the repository
Clone the files-mcp-server repository to your local machine and install dependencies using Bun.
git clone https://github.com/iceener/files-stdio-mcp-server.git
cd files-stdio-mcp-server
bun installCreate a .env configuration file
Create a .env file in the project root specifying which directories the agent is allowed to access. Multiple paths are separated by commas.
FS_ROOTS=/Users/you/projects,/Users/you/documents
LOG_LEVEL=infoTest the server locally
Run the server in development mode to verify it starts correctly before connecting to Claude Desktop.
bun devConfigure Claude Desktop
Add the files MCP server to your Claude Desktop configuration. Point to the built server script and set FS_ROOTS in the env block.
{
"mcpServers": {
"files": {
"command": "bun",
"args": ["/absolute/path/to/files-stdio-mcp-server/src/index.ts"],
"env": {
"FS_ROOTS": "/Users/you/projects",
"LOG_LEVEL": "info"
}
}
}
}Restart Claude Desktop and verify
Fully quit and relaunch Claude Desktop. Ask Claude to list the contents of your configured root directory to confirm the connection is working.
Files Examples
Client configuration
Claude Desktop configuration with FS_ROOTS pointing to a projects directory.
{
"mcpServers": {
"files": {
"command": "bun",
"args": ["/Users/you/files-stdio-mcp-server/src/index.ts"],
"env": {
"FS_ROOTS": "/Users/you/projects",
"MAX_FILE_SIZE": "5242880"
}
}
}
}Prompts to try
Once connected, use these prompts to explore and edit files through Claude.
- "List all files in my projects directory and show me the folder structure"
- "Find all TypeScript files that import from 'react-router' in my project"
- "Read the contents of src/index.ts and suggest improvements"
- "Search for all TODO comments across the codebase"
- "Preview what would change if you rename the function 'fetchUser' to 'getUser' in all files"Troubleshooting Files
Agent refuses to access a file outside the configured roots
This is intentional sandbox behavior. Add the required directory path to FS_ROOTS in your .env file or MCP config env block. Separate multiple paths with commas: FS_ROOTS=/path/one,/path/two.
File write fails with 'checksum mismatch'
The server requires reading a file before modifying it to ensure consistency. Use the fs_read tool to read the file first — this provides the checksum that must accompany the fs_write call.
Bun command not found when starting the server
Install Bun by running: curl -fsSL https://bun.sh/install | bash. After installation, restart your terminal and verify with 'bun --version'. Alternatively, use Node.js with 'npx ts-node src/index.ts'.
Frequently Asked Questions about Files
What is Files?
Files is a Model Context Protocol (MCP) server that enables ai agents to safely explore directories, read files, search content by pattern or filename, and edit files with checksum verification and dry-run preview within sandboxed filesystem access. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Files?
Follow the installation instructions on the Files GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Files?
Files works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Files free to use?
Yes, Files is open source and available under the ISC License license. You can use it freely in both personal and commercial projects.
Files Alternatives — Similar File Systems Servers
Looking for alternatives to Files? Here are other popular file systems servers you can use with Claude, Cursor, and VS Code.
Electerm
★ 14.1k📻Terminal/ssh/sftp/ftp/telnet/serialport/RDP/VNC/Spice client(linux, mac, win)
Plik
★ 1.8kPlik is a temporary file upload system (Wetransfer like) in Go.
Kordoc
★ 957An MCP server that parses South Korean document formats like HWP, HWPX, and PDF into Markdown. It features specialized table reconstruction and security-hardened extraction optimized for administrative and public institution files.
macOS Automator
★ 801A Model Context Protocol server that enables execution of AppleScript and JavaScript for Automation scripts on macOS, allowing programmatic control of applications and system functions through a rich knowledge base of pre-defined scripts.
PDF Reader
★ 723Enables reading, searching, and metadata extraction from PDF files without loading the entire content into the context window. It provides efficient tools for text cleaning, page-specific extraction, and context-aware search results.
Filesystem MCP Server
★ 643Provides comprehensive filesystem operations (read, write, list, create, delete, move files and directories) through the Model Context Protocol with Streamable HTTP transport and built-in security through configurable root directory restrictions.
Browse More File Systems MCP Servers
Explore all file systems servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Files in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Files?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.