Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@filesystem-mcp list files in the current directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol (MCP) server for file system operations. Enable AI assistants like Claude, Cursor, and others to read, write, and manage files on your local system.
📖 Read files - Read file contents with size limits
📂 List directories - View files with metadata (size, type)
✏️ Write files - Create and update files
🗑️ Delete files - Remove files and directories
🔍 Search files - Glob pattern matching
📊 File info - Get detailed metadata
📁 Directory operations - Create, copy, move directories
Related MCP server: Filesystem MCP
pip install filesystem-mcp# Start the MCP server (read-write mode)
filesystem-mcp --directory /path/to/your/project
# Start in read-only mode
filesystem-mcp --directory /path/to/your/project --readonlyAdd to your claude_desktop_config.json:
{
"mcpServers": {
"filesystem": {
"command": "filesystem-mcp",
"args": ["--directory", "/path/to/your/project"]
}
}
}Add to Cursor settings (MCP configuration):
{
"mcpServers": {
"filesystem": {
"command": "filesystem-mcp",
"args": ["--directory", "/path/to/your/project"]
}
}
}Tool | Description | Write |
| Read contents of a file | ❌ |
| List files in a directory | ❌ |
| Create or write to a file | ✅ |
| Delete a file or directory | ✅ |
| Create a new directory | ✅ |
| Search files by glob pattern | ❌ |
| Get file metadata | ❌ |
| Copy a file or directory | ✅ |
| Move or rename a file | ✅ |
from filesystem_mcp import FileSystemServer
# Create server instance
server = FileSystemServer(root_directory="/path/to/project")
# Run the server
server.run()Path restrictions: All operations are restricted to the specified root directory
File size limits: Maximum 1MB for file reads
Optional read-only mode: Use --readonly flag to disable all write operations
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
MIT License - see LICENSE for details.
Copy a file or directory
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Source path | |
| destination | Yes | Destination path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose key behaviors such as overwrite rules, recursive copying, or error handling. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at two words, front-loaded, but lacks essential details. Every word earns its place, but could be expanded for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description fails to explain behavior for directories, return values, or conflicts. Incomplete given the complexity of the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptions in the schema (100% coverage). The description adds no additional meaning beyond the schema's 'Source path' and 'Destination path', so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Copy' and the resource 'file or directory', distinguishing it from sibling tools like move_file, create_directory, or delete_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus others like move_file. No mention of prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new directory
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the action. It does not disclose behavior for existing directories, intermediate path creation, or permissions, leaving important gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence directly stating the purpose with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is adequate but lacks crucial details like behavior on conflicts or idempotency, making it only medium value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, and the description does not add extra meaning beyond the schema's 'Relative path to directory'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new directory' clearly states the action (create) and the resource (directory), distinguishing it from sibling file tools like copy_file or delete_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when to create a directory vs. a file, or what happens if the directory already exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file or directory
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to delete | |
| recursive | No | Delete directories recursively |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It fails to mention important aspects like permanent deletion, permission requirements, or behavior with non-empty directories beyond the recursive parameter implicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. No unnecessary words, perfect for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a destructive tool with no annotations and no output schema, the description is incomplete. It does not explain side effects, return values, or error conditions, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for both parameters. The description adds minimal extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a file or directory' clearly states the verb (delete) and the resource (file or directory), and is distinct from sibling tools like copy_file or read_file which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives such as move_file or copy_file. Lacks any mention of prerequisites, contexts, or comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed file metadata
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits such as that this is a read-only operation (though inferable), or what exactly 'detailed' metadata includes (e.g., size, permissions, timestamps). No annotations are present to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at five words, with no wasted text. It front-loads the purpose and is structured effectively for an agent to quickly understand the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description is insufficient. It fails to specify what metadata is returned or any notable constraints, leaving the agent with incomplete information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the 'path' parameter with 100% coverage. The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get detailed file metadata' clearly identifies the verb ('get') and resource ('file metadata'). It distinguishes from sibling tools that perform file operations like copy, delete, or read content, as it focuses on metadata retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not clarify that this tool should be used when metadata is needed, not file content, nor does it mention that it is safe for repeated use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and directories with metadata
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to directory | |
| show_hidden | No | Show hidden files |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description says 'with metadata' but does not specify what metadata or note any behavioral traits (e.g., read-only nature, permissions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise, but omits important details like return format and scope. Front-loaded with purpose, but incomplete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description fails to specify what metadata is returned (size, date, type, permissions). Also lacks detail on whether listing is recursive. Incomplete for a file listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions; description adds no extra meaning beyond 'with metadata', which is about output, not parameters. Baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists files and directories with metadata, distinguishing it from get_file_info (single file) and search_files (search). Could be more specific about scope (e.g., current directory vs. recursive).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like get_file_info or search_files. Agent must infer from name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move or rename a file or directory
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Source path | |
| destination | Yes | Destination path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only says 'move or rename' but omits critical details: whether the source is deleted, if directories are moved recursively, whether overwriting occurs, or any permission requirements. The behavioral traits are largely unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief (one sentence), which is concise but lacking structure. It could benefit from a list or additional sentences to cover usage notes without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature (move/rename), the description is incomplete. It lacks details about return values, error handling, directory behavior, and overwrite policies, which are essential for an AI agent to use it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes the two parameters ('source' and 'destination'). The description adds no additional semantic value beyond the schema, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('move or rename') and resource ('file or directory'). It distinguishes from sibling tools like copy_file and delete_file, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like copy_file or rename. There is no mention of prerequisites, when to choose move over copy, or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read contents of a file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It fails to mention what happens if the file does not exist, encoding, size limits, or error handling, leaving critical gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. However, it could be improved by adding a bit more context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description fails to specify the return format (e.g., string or buffer), error behavior, or file existence requirements, making it incomplete for safe agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter 'path' described as 'Relative path to the file'. The description adds no additional meaning beyond the schema, meeting the baseline but not enhancing understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Read contents of a file' clearly specifies the action (read) and the resource (file), distinguishing it from sibling tools like write_file, delete_file, and copy_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or not use this tool; usage is implied by the tool name and siblings, but no alternatives or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search files by glob pattern
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | Glob pattern (e.g., *.py, **/*.js) | |
| path | No | Base path to search from | . |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose what is returned (file paths, names, or content), behavior on no matches, or recursive behavior. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Efficient but could benefit from additional context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 2 parameters, no output schema, and no annotations. Description is too minimal to fully inform an agent; lacks mention of return format and behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds no extra meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'search' and resource 'files', with method 'glob pattern'. Distinguishes from sibling tools like list_directory and read_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like list_directory or grep-like tools. Lacks context on when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or write to a file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to file | |
| content | Yes | Content to write | |
| append | No | Append to file instead of overwriting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose that the default behavior is overwriting, nor does it mention the append parameter. The brief description lacks important behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Only one sentence, but it omits crucial details such as append behavior and differentiation from siblings. Under-specified rather than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no output schema, and multiple sibling tools, missing information about default behavior, error handling, and return format makes the description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The description adds no additional meaning beyond the schema, meeting baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool creates or writes to a file, distinguishing from read, delete, and search siblings. However, it doesn't explicitly mention the append capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like copy_file or read_file. No mention of prerequisites or when appending is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0copy_filecreate_directorydelete_fileget_file_infolist_directorymove_fileread_filesearch_fileswrite_fileScored across 9 tools
Each tool targets a distinct filesystem operation with no overlap, making selection unambiguous.
All tool names follow a consistent verb_noun pattern in snake_case, e.g., copy_file, create_directory.
9 tools cover essential filesystem operations without being excessive or insufficient.
The set covers CRUD for files and directories, listing, searching, metadata, and move/rename with no obvious gaps.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
File uploads for AI agents. Upload, list, and manage files. No signup required.
Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.
Securely search and manage workspace context files for AI agents and teams.
