This project is a Python-based MCP (Model Context Protocol) server that allows Claude Desktop, OpenCode, and Antigravity CLI to perform secure and controlled local filesystem operations via natural language commands. It bridges the gap between conversational AI and direct file management by implementing the MCP 1.0 protocol with full support for read/write operations, file system traversal, metadata extraction, and optional cryptographic operation receipts.
- ✅ Fully compatible with Claude Desktop, OpenCode, and Antigravity CLI
- 📂 Read, write, move, copy, delete, and search files and directories
- 🔒 Thread-safe deterministic locking, strict path validation & extension policy enforcement
- 🧠 JSON-RPC 2.0 communication over
stdin/stdout - 🔄 Asynchronous architecture with
asyncio - 🧾 Optional Ed25519-signed BoundaryAttest receipts for high-impact file operations
- 🧪 Unit & integration tests included
- Python >= 3.11
- MCP SDK (
mcp[cli] >= 1.10.1), send2trash - AsyncIO, Pathlib, JSON, Typing
- Claude Desktop, OpenCode, Antigravity CLI
- MCP Protocol (v1.0) implementation
On Windows PowerShell:
powershell -ExecutionPolicy ByPass -c "irm [https://astral.sh/uv/install.ps1](https://astral.sh/uv/install.ps1) | iex"On Linux / macOS:
curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | shOr if your system does not have curl, use wget:
wget -qO- [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | shMake sure
uvis available in your systemPATH.
git clone [https://github.com/CodingWithMK/filesystem_mcp_server.git](https://github.com/CodingWithMK/filesystem_mcp_server.git)
cd filesystem_mcp_server
uv syncTo install optional dependencies for testing or BoundaryAttest receipts:
# Install test dependencies (pytest, cryptography)
uv sync --extra test
# Install optional BoundaryAttest receipt signing dependency (cryptography)
uv sync --extra boundaryattestEdit config/windows.json, config/macos.json, or config/default.json to define allowed paths, maximum file size, and allowed file extensions:
config/windows.json
{
"allowed_paths": [
"~/Desktop",
"~/Downloads"
],
"max_file_size": "20MB",
"allowed_extensions": [
"txt", "md", "pdf", "png", "jpg", "jpeg", "json", "docx", "doc", "ppt",
"pptx", "xls", "xlsx", "mp4", "mp3", "wav", "avi", "mov", "zip", "rar",
"msi", "exe", "dll", "py", "c", "cpp", "java", "js", "html", "css", "xml", "csv", "ts",
"CATPart", "CATProduct", "CATDrawing", "CATProcess"
]
}config/macos.json
{
"allowed_paths": [
"~/Desktop",
"~/Downloads"
],
"max_file_size": "20MB",
"allowed_extensions": [
"txt", "md", "pdf", "png", "jpg", "jpeg", "json", "docx", "doc", "ppt",
"pptx", "xls", "xlsx", "mp4", "mp3", "wav", "avi", "mov", "zip", "rar",
"pkg", "dmg", "dll", "py", "c", "cpp", "java", "js", "html", "css", "xml", "csv", "ts"
]
}config/default.json
{
"allowed_paths": [
"~/Desktop",
"~/Downloads"
],
"max_file_size": "20MB",
"allowed_extensions": [
"txt", "md", "pdf", "png", "jpg", "jpeg", "json", "docx", "doc", "ppt",
"pptx", "xls", "xlsx", "mp4", "mp3", "wav", "avi", "mov", "zip", "rar",
"msi", "exe", "pkg", "dmg", "dll", "py", "c", "cpp", "java", "js", "html", "css", "xml", "csv", "ts",
"CATPart", "CATProduct", "CATDrawing", "CATProcess"
]
}You can optionally override the JSON configuration via environment variables:
FILESYSTEM_ALLOWED_PATHS: OS path-separated list of allowed directories (e.g.,:on Linux/macOS,;on Windows)FILESYSTEM_MAX_FILE_SIZE: Maximum allowed file size (e.g.,20MB,500KB,1GB)FILESYSTEM_ALLOWED_EXTENSIONS: Comma-separated list of allowed extensions (e.g.,txt,md,py,json)
{
"mcpServers": {
"python-filesystem": {
"command": "C:\\Users\\username\\.local\\bin\\uv.exe",
"args": [
"run",
"--with",
"mcp[cli]",
"mcp",
"run",
"C:\\Users\\username\\Documents\\filesystem_mcp_server\\src\\main.py"
]
}
}
}Open your global OpenCode
.configdirectory and editopencode.jsonc:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"filesystem_mcp_server": {
"type": "local",
"enabled": true,
"command": [
"C:\\Users\\username\\.local\\bin\\uv.exe",
"run",
"--project",
"C:\\Users\\username\\Documents\\filesystem_mcp_server",
"python",
"C:\\Users\\username\\Documents\\filesystem_mcp_server\\src\\main.py"
]
}
}
}Open your global standalone Antigravity CLI MCP configuration file under
.gemini/config/mcp_config.jsonand adjust the paths to your system:
{
"mcpServers": {
"filesystem-mcp-server": {
"command": "C:\\Users\\username\\.local\\bin\\uv.exe",
"args": [
"run",
"--project",
"C:\\Users\\username\\Documents\\filesystem_mcp_server",
"python",
"C:\\Users\\username\\Documents\\filesystem_mcp_server\\src\\main.py"
],
"env": {}
}
}
}read_file: Reads plaintext UTF-8 content from an approved filewrite_file: Writes or appends UTF-8 text payloads to a file safelymove_file: Moves files safely under deterministic synchronization lockscopy_file: Copies files with metadata preservation (shutil.copy2)delete_file: Moves a file to the operating system recycling bin viasend2trashsearch_file: Recursively searches for files matching a keyword in their filenameget_file_info: Retrieves safe metadata (name,size,modified,is_directory)
list_files: Lists all files inside a directorylist_directories: Lists all subdirectories inside a directorylist_directory_content: Lists all entries (both files and folders) in a directorycreate_directory: Recursively creates directories inside authorized pathsmove_directory: Moves folder trees with deterministic lockingcopy_directory: Performs recursive directory cloningdelete_directory: Moves a directory structure to the OS recycling binget_allowed_paths: Returns the currently configured allowed root paths
All handlers run asynchronously via worker threads and enforce path boundary checks, extension whitelists, and deadlock-free locking.
Run the BoundaryAttest and core operation test suite using uv:
uv run --extra test pytest tests/test_boundaryattest.pyIncludes tests for:
- File I/O (
write_file,move_file,delete_file) & exact byte preservation - Path validation & deterministic lock verification
- Optional BoundaryAttest receipt signing, verification, and tamper detection
The server can optionally emit portable, Ed25519-signed BoundaryAttest Interop Profile v0.1 receipts after successful write_file, move_file, and delete_file operations. This proof of concept is off by default: ordinary single-user/local MCP deployments generally get sufficient visibility from their existing MCP and local logs, without signing-key or receipt-storage overhead. The feature is aimed at shared, multi-tenant, enterprise, CI/CD, and other trust-boundary environments where portable evidence may be useful.
Install the optional dependency and configure the server process:
uv sync --extra boundaryattest
export BOUNDARYATTEST_ENABLED=true
export BOUNDARYATTEST_PRIVATE_KEY=/secure/path/ed25519-private-key.pem
export BOUNDARYATTEST_RECEIPT_DIR=/secure/path/filesystem-receiptsFor development only, generate an Ed25519 PKCS #8 key (never commit it):
openssl genpkey -algorithm Ed25519 -out boundaryattest-dev-private.pem
openssl pkey -in boundaryattest-dev-private.pem -pubout -out boundaryattest-dev-public.pemEach successful covered operation writes one uniquely named JSON receipt. Clear path references are relative to the matching configured allowed root, while the signed materialized_action_hash binds the exact resolved internal path(s). Writes bind the appended UTF-8 content digest plus exact pre/post file hashes; moves bind the source and actual final destination (including an appended source name when the destination argument is a directory); deletes bind the exact pre-trash bytes and have no post-delete artifact at the original path. File hashes are SHA-256 over raw bytes.
Verify with a public key obtained through a trusted path, optionally checking a current artifact's exact bytes:
uv run --extra boundaryattest python src/verify_boundaryattest_receipt.py \
RECEIPT.json EXPECTED_PUBLIC_KEY.pem --artifact FILEA valid result proves only that the expected key signed the unchanged claim and, when supplied, that the artifact bytes match the signed digest. It does not prove truth, wisdom, authorization, policy compliance, signer trustworthiness, runtime integrity, or production-grade key custody. The feature is experimental, non-transactional, and external to the MCP server: if an action succeeds but receipt emission fails, the action is not rolled back and the tool returns its success message with a prominent attestation warning. This invited test integration is not an endorsement, partnership, audit system, security guarantee, or production key-management system.
- Unsupported File Extensions: If an agent cannot read or write a specific file type, add the extension to
allowed_extensionsinconfig/windows.json,config/macos.json, orconfig/default.json(or viaFILESYSTEM_ALLOWED_EXTENSIONS). - Path /
uvResolution: Ensureuvis installed and referenced with its full path in your MCP client config if the client does not inherit your shellPATH.
Contributions are welcome! Whether it's bug fixes, new features, or documentation improvements, feel free to fork the repository and submit a Pull Request.
MIT License
- Inspired by the official Filesystem MCP Server from Anthropic
- Based on the MCP 1.0 Protocol Specification