MCP File Manager — File System Operations for AI Agents

An MCP server that gives AI agents file system access: read, write, search, hash, directory trees — 12 tools, zero dependencies, pure Python stdlib.

Features

• 12 MCP Tools: read_file, read_file_lines, write_file, append_file, delete_file, copy_file, move_file, list_directory, search_files, file_info, file_hash, directory_tree
• Zero dependencies — pure Python stdlib (os, shutil, hashlib, fnmatch, pathlib)
• Content search — grep-like search inside files (20+ file extensions)
• File hashing — MD5, SHA-1, SHA-256, SHA-512
• Directory trees — recursive tree generation with depth control
• STDIO JSON-RPC mode — drop-in for Claude Desktop, Hermes, or any MCP client

Quick Start

python -m src.server --stdio    # STDIO mode
python -m src.server --manifest # Print manifest

Use as a library

from src.server import MCPFileManagerServer
import json

server = MCPFileManagerServer()

# Write a file
server.handle_tool_call("write_file", {"path": "/tmp/test.txt", "content": "Hello!"})

# Read it back
result = json.loads(server.handle_tool_call("read_file", {"path": "/tmp/test.txt"}))
print(result["content"])  # "Hello!"

# Search for files
result = server.handle_tool_call("search_files", {"path": ".", "pattern": "*.py", "target": "files"})

# Search inside files (grep)
result = server.handle_tool_call("search_files", {"path": ".", "pattern": "TODO", "target": "content"})

# Get file hash
result = server.handle_tool_call("file_hash", {"path": "/tmp/test.txt", "algorithm": "sha256"})

# Directory tree
result = server.handle_tool_call("directory_tree", {"path": ".", "max_depth": 3})

MCP Tool Reference

Tool	Description	Required Params
read_file	Read file content	path
read_file_lines	Read specific lines	path
write_file	Write file (creates dirs)	path, content
append_file	Append to file	path, content
delete_file	Delete file or dir	path
copy_file	Copy file or dir	src, dst
move_file	Move/rename	src, dst
list_directory	List dir contents	—
search_files	Find by name or grep	pattern
file_info	File metadata	path
file_hash	File hash (md5/sha256)	path
directory_tree	Directory tree	—

Tests

python -m pytest tests/ -v  # 36 tests, all passing

License

MIT

Author

aaameobius-crypto — github.com/aaameobius-crypto

Freelance portfolio: https://ameobius-space.github.io/kwork-portfolio/