Skip to content

Commit 5f02ce4

Browse files
ezynda3ezynda3
committed
Make exportable as a package
1 parent 33390d5 commit 5f02ce4

File tree

3 files changed

+1783
-1736
lines changed

3 files changed

+1783
-1736
lines changed

‎README.md

Lines changed: 118 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,149 @@
1-
[![smithery badge](https://smithery.ai/badge/@mark3labs/mcp-filesystem-server)](https://smithery.ai/server/@mark3labs/mcp-filesystem-server)
1+
# MCP Filesystem Server
22

3-
# Filesystem MCP Server
3+
This MCP server provides secure access to the local filesystem via the Model Context Protocol (MCP).
44

5-
Go server implementing Model Context Protocol (MCP) for filesystem operations.
5+
## Components
66

7-
## Features
8-
9-
- Read/write files
10-
- Create/list/delete directories
11-
- Move files/directories
12-
- Search files
13-
- Get file metadata
14-
- Generate directory tree structures
15-
16-
**Note**: The server will only allow operations within directories specified via `args`.
17-
18-
## API
7+
### Tools
198

20-
### Resources
9+
#### File Operations
2110

22-
- `file://system`: File system operations interface
11+
- **read_file**
12+
- Read the complete contents of a file from the file system
13+
- Parameters: `path` (required): Path to the file to read
2314

24-
### Tools
15+
- **write_file**
16+
- Create a new file or overwrite an existing file with new content
17+
- Parameters: `path` (required): Path where to write the file, `content` (required): Content to write to the file
2518

26-
- **read_file**
27-
- Read complete contents of a file
28-
- Input: `path` (string)
29-
- Reads complete file contents with UTF-8 encoding
19+
- **move_file**
20+
- Move or rename files and directories
21+
- Parameters: `source` (required): Source path of the file or directory, `destination` (required): Destination path
3022

31-
- **read_multiple_files**
32-
- Read multiple files simultaneously
33-
- Input: `paths` (string[])
34-
- Failed reads won't stop the entire operation
23+
#### Directory Operations
3524

36-
- **write_file**
37-
- Create new file or overwrite existing (exercise caution with this)
38-
- Inputs:
39-
- `path` (string): File location
40-
- `content` (string): File content
25+
- **list_directory**
26+
- Get a detailed listing of all files and directories in a specified path
27+
- Parameters: `path` (required): Path of the directory to list
4128

4229
- **create_directory**
43-
- Create new directory or ensure it exists
44-
- Input: `path` (string)
45-
- Creates parent directories if needed
46-
- Succeeds silently if directory exists
30+
- Create a new directory or ensure a directory exists
31+
- Parameters: `path` (required): Path of the directory to create
4732

48-
- **list_directory**
49-
- List directory contents with [FILE] or [DIR] prefixes
50-
- Input: `path` (string)
33+
- **tree**
34+
- Returns a hierarchical JSON representation of a directory structure
35+
- 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)
5136

52-
- **move_file**
53-
- Move or rename files and directories
54-
- Inputs:
55-
- `source` (string)
56-
- `destination` (string)
57-
- Fails if destination exists
37+
#### Search and Information
5838

5939
- **search_files**
60-
- Recursively search for files/directories
61-
- Inputs:
62-
- `path` (string): Starting directory
63-
- `pattern` (string): Search pattern
64-
- Case-insensitive matching
65-
- Returns full paths to matches
40+
- Recursively search for files and directories matching a pattern
41+
- Parameters: `path` (required): Starting path for the search, `pattern` (required): Search pattern to match against file names
6642

6743
- **get_file_info**
68-
- Get detailed file/directory metadata
69-
- Input: `path` (string)
70-
- Returns:
71-
- Size
72-
- Creation time
73-
- Modified time
74-
- Access time
75-
- Type (file/directory)
76-
- Permissions
77-
78-
- **tree**
79-
- Returns a hierarchical JSON representation of a directory structure
80-
- Inputs:
81-
- `path` (string): Directory to traverse (required)
82-
- `depth` (number): Maximum depth to traverse (default: 3)
83-
- `follow_symlinks` (boolean): Whether to follow symbolic links (default: false)
84-
- Returns formatted JSON with file/directory hierarchy
85-
- Includes file metadata (name, path, size, modified time)
44+
- Retrieve detailed metadata about a file or directory
45+
- Parameters: `path` (required): Path to the file or directory
8646

8747
- **list_allowed_directories**
88-
- List all directories the server is allowed to access
89-
- No input required
90-
- Returns:
91-
- Directories that this server can read/write from
48+
- Returns the list of directories that this server is allowed to access
49+
- Parameters: None
50+
51+
## Features
52+
53+
- Secure access to specified directories
54+
- Path validation to prevent directory traversal attacks
55+
- Symlink resolution with security checks
56+
- MIME type detection
57+
- Support for text, binary, and image files
58+
- Size limits for inline content and base64 encoding
59+
60+
## Getting Started
61+
62+
### Installation
63+
64+
#### Using Go Install
65+
66+
```bash
67+
go install github.com/mark3labs/mcp-filesystem-server@latest
68+
```
69+
70+
### Usage
71+
72+
#### As a standalone server
73+
74+
Start the MCP server with allowed directories:
9275

93-
## Usage with Claude Desktop
94-
Install the server
9576
```bash
96-
go install github.com/mark3labs/mcp-filesystem-server
77+
mcp-filesystem-server /path/to/allowed/directory [/another/allowed/directory ...]
9778
```
9879

99-
Add this to your `claude_desktop_config.json`:
80+
#### As a library in your Go project
81+
82+
```go
83+
package main
84+
85+
import (
86+
"log"
87+
"os"
88+
89+
"github.com/mark3labs/mcp-filesystem-server/filesystemserver"
90+
)
91+
92+
func main() {
93+
// Create a new filesystem server with allowed directories
94+
allowedDirs := []string{"/path/to/allowed/directory", "/another/allowed/directory"}
95+
fs, err := filesystemserver.NewFilesystemServer(allowedDirs)
96+
if err != nil {
97+
log.Fatalf("Failed to create server: %v", err)
98+
}
99+
100+
// Serve requests
101+
if err := fs.Serve(); err != nil {
102+
log.Fatalf("Server error: %v", err)
103+
}
104+
}
105+
```
106+
107+
### Usage with Model Context Protocol
108+
109+
To integrate this server with apps that support MCP:
110+
100111
```json
101112
{
102113
"mcpServers": {
103114
"filesystem": {
104115
"command": "mcp-filesystem-server",
116+
"args": ["/path/to/allowed/directory", "/another/allowed/directory"]
117+
}
118+
}
119+
}
120+
```
121+
122+
### Docker
123+
124+
#### Running with Docker
125+
126+
You can run the Filesystem MCP server using Docker:
127+
128+
```bash
129+
docker run -i --rm ghcr.io/mark3labs/mcp-filesystem-server:latest /path/to/allowed/directory
130+
```
131+
132+
#### Docker Configuration with MCP
133+
134+
To integrate the Docker image with apps that support MCP:
135+
136+
```json
137+
{
138+
"mcpServers": {
139+
"filesystem": {
140+
"command": "docker",
105141
"args": [
106-
"/Users/username/Desktop",
107-
"/path/to/other/allowed/dir"
142+
"run",
143+
"-i",
144+
"--rm",
145+
"ghcr.io/mark3labs/mcp-filesystem-server:latest",
146+
"/path/to/allowed/directory"
108147
]
109148
}
110149
}
@@ -113,4 +152,4 @@ Add this to your `claude_desktop_config.json`:
113152

114153
## License
115154

116-
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
155+
See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)