MCP Filesystem Server

1# MCP Filesystem Server
2 
3This MCP server provides secure access to the local filesystem via the Model Context Protocol (MCP).
4 
5## Components
6 
7### Resources
8 
9- **file://**
10  - Name: File System
11  - Description: Access to files and directories on the local file system
12 
13### Tools
14 
15#### File Operations
16 
17- **read_file**
18  - Read the complete contents of a file from the file system
19  - Parameters: `path` (required): Path to the file to read
20 
21- **read_multiple_files**
22  - Read the contents of multiple files in a single operation
23  - Parameters: `paths` (required): List of file paths to read
24 
25- **write_file**
26  - Create a new file or overwrite an existing file with new content
27  - Parameters: `path` (required): Path where to write the file, `content` (required): Content to write to the file
28 
29- **copy_file**
30  - Copy files and directories
31  - Parameters: `source` (required): Source path of the file or directory, `destination` (required): Destination path
32 
33- **move_file**
34  - Move or rename files and directories
35  - Parameters: `source` (required): Source path of the file or directory, `destination` (required): Destination path
36 
37- **delete_file**
38  - Delete a file or directory from the file system
39  - Parameters: `path` (required): Path to the file or directory to delete, `recursive` (optional): Whether to recursively delete directories (default: false)
40 
41- **modify_file**
42  - Update file by finding and replacing text using string matching or regex
43  - Parameters: `path` (required): Path to the file to modify, `find` (required): Text to search for, `replace` (required): Text to replace with, `all_occurrences` (optional): Replace all occurrences (default: true), `regex` (optional): Treat find pattern as regex (default: false)
44 
45#### Directory Operations
46 
47- **list_directory**
48  - Get a detailed listing of all files and directories in a specified path
49  - Parameters: `path` (required): Path of the directory to list
50 
51- **create_directory**
52  - Create a new directory or ensure a directory exists
53  - Parameters: `path` (required): Path of the directory to create
54 
55- **tree**
56  - Returns a hierarchical JSON representation of a directory structure
57  - Parameters: `path` (required): Path of the directory to traverse, `depth` (optional): Maximum depth to traverse (default: 3), `follow_symlinks` (optional): Whether to follow symbolic links (default: false)
58 
59#### Search and Information
60 
61- **search_files**
62  - Recursively search for files and directories matching a pattern
63  - Parameters: `path` (required): Starting path for the search, `pattern` (required): Search pattern to match against file names
64 
65- **search_within_files**
66  - Search for text within file contents across directory trees
67  - Parameters: `path` (required): Starting directory for the search, `substring` (required): Text to search for within file contents, `depth` (optional): Maximum directory depth to search, `max_results` (optional): Maximum number of results to return (default: 1000)
68 
69- **get_file_info**
70  - Retrieve detailed metadata about a file or directory
71  - Parameters: `path` (required): Path to the file or directory
72 
73- **list_allowed_directories**
74  - Returns the list of directories that this server is allowed to access
75  - Parameters: None
76 
77## Features
78 
79- Secure access to specified directories
80- Path validation to prevent directory traversal attacks
81- Symlink resolution with security checks
82- MIME type detection
83- Support for text, binary, and image files
84- Size limits for inline content and base64 encoding
85 
86## Getting Started
87 
88### Installation
89 
90#### Using Go Install
91 
92```bash
93go install github.com/mark3labs/mcp-filesystem-server@latest
94```
95 
96### Usage
97 
98#### As a standalone server
99 
100Start the MCP server with allowed directories:
101 
102```bash
103mcp-filesystem-server /path/to/allowed/directory [/another/allowed/directory ...]
104```
105 
106#### As a library in your Go project
107 
108```go
109package main
110 
111import (
112	"log"
113	"os"
114 
115	"github.com/mark3labs/mcp-filesystem-server/filesystemserver"
116)
117 
118func main() {
119	// Create a new filesystem server with allowed directories
120	allowedDirs := []string{"/path/to/allowed/directory", "/another/allowed/directory"}
121	fs, err := filesystemserver.NewFilesystemServer(allowedDirs)
122	if err != nil {
123		log.Fatalf("Failed to create server: %v", err)
124	}
125 
126	// Serve requests
127	if err := fs.Serve(); err != nil {
128		log.Fatalf("Server error: %v", err)
129	}
130}
131```
132 
133### Usage with Model Context Protocol
134 
135To integrate this server with apps that support MCP:
136 
137```json
138{
139  "mcpServers": {
140    "filesystem": {
141      "command": "mcp-filesystem-server",
142      "args": ["/path/to/allowed/directory", "/another/allowed/directory"]
143    }
144  }
145}
146```
147 
148### Docker
149 
150#### Running with Docker
151 
152You can run the Filesystem MCP server using Docker:
153 
154```bash
155docker run -i --rm ghcr.io/mark3labs/mcp-filesystem-server:latest /path/to/allowed/directory
156```
157 
158#### Docker Configuration with MCP
159 
160To integrate the Docker image with apps that support MCP:
161 
162```json
163{
164  "mcpServers": {
165    "filesystem": {
166      "command": "docker",
167      "args": [
168        "run",
169        "-i",
170        "--rm",
171        "ghcr.io/mark3labs/mcp-filesystem-server:latest",
172        "/path/to/allowed/directory"
173      ]
174    }
175  }
176}
177```
178 
179If you need changes made inside the container to reflect on the host filesystem, you can mount a volume. This allows the container to access and modify files on the host system. Here's an example:
180 
181```json
182{
183  "mcpServers": {
184    "filesystem": {
185      "command": "docker",
186      "args": [
187        "run",
188        "-i",
189        "--rm",
190        "--volume=/allowed/directory/in/host:/allowed/directory/in/container",
191        "ghcr.io/mark3labs/mcp-filesystem-server:latest",
192        "/allowed/directory/in/container"
193      ]
194    }
195  }
196}
197```
198 
199## License
200 
201See the [LICENSE](LICENSE) file for details.
202