🗂️ MCP Filesystem Assistant
A beautiful AI-powered file manager built with Model Context Protocol (MCP), featuring a modern web interface, OpenAI integration, and secure filesystem operations.
🎯 What is This?
An AI assistant that can read, write, and manage your files through natural language. Built on the Model Context Protocol (MCP), it demonstrates how to:
- 🤖 Connect AI models to real tools
- 🔒 Safely manage files in a sandboxed environment
- 🎨 Build beautiful interfaces with Streamlit
- 🛠️ Create production-ready MCP servers
Perfect for learning MCP or building your own AI-powered tools!
✨ Features
💬 Natural Language Interface
Ask the AI to manage files in plain English:
- "List all files in the workspace"
- "Read notes.txt and summarize it"
- "Create a backup folder and organize my files"
- "Show me details about data.json"
🎨 Beautiful Web Interface
- Chat Tab - Talk to the AI assistant
- File Browser - Visual workspace explorer
- Quick Actions - Direct file operations without AI
🛠️ 8 Powerful Tools
| Tool | What it does |
|---|---|
read_file | Read file contents |
write_file | Create or overwrite files |
append_file | Add to existing files |
delete_file | Remove files safely |
list_directory | Browse folders |
create_directory | Make new folders |
move_file | Rename or relocate files |
get_file_info | Show file details |
🔒 Security First
- All operations sandboxed to
workspace/folder - Path traversal protection
- Input validation on every operation
📁 Project Structure
filesystem-mcp-project/
├── host/ # Streamlit web app
│ ├── app.py # Main interface
│ ├── mcp_connector.py # Connects to MCP server
│ └── ui_components.py # UI styling
│
├── server/ # MCP server
│ ├── filesystem_mcp_server.py # 8 filesystem tools
│ └── config.py # Settings
│
├── workspace/ # Your files live here
│ ├── notes.txt
│ └── data.json
│
├── requirements.txt # Python packages
├── .env.example # Config template
└── README.md # You are here!
🚀 Quick Start
1. Install
# Clone or download the project
cd filesystem-mcp-project
# Create virtual environment
python -m venv venv
# Activate it
source venv/bin/activate # Mac/Linux
# OR
venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
2. Configure
Create a .env file:
OPENAI_API_KEY=sk-your-key-here
Get your OpenAI API key from: https://platform.openai.com/api-keys
3. Run
Terminal 1 - Start MCP Server:
python server/filesystem_mcp_server.py
You should see:
🚀 MCP Server starting...
📁 Workspace directory: /path/to/workspace
🌐 Server running on http://127.0.0.1:8000
✅ Available tools: 8
Terminal 2 - Launch Web Interface:
streamlit run host/app.py
Browser opens at http://localhost:8501 🎉
💡 Usage Examples
Example 1: List Files
You: "What files are in the workspace?"
AI: Uses list_directory tool
📁 Directory: .
📄 notes.txt (1.2 KB)
📄 data.json (856 bytes)
Example 2: Create File
You: "Create a file called hello.txt with 'Hello World!'"
AI: Uses write_file tool
✅ File written successfully: hello.txt (12 characters)
Example 3: Organize Files
You: "Create a backup folder and move old files into it"
AI: Uses create_directory and move_file tools
✅ Directory created: backup
✅ File moved: old_data.txt → backup/old_data.txt
🏗️ How It Works
┌─────────────────┐
│ You (User) │
│ Ask questions │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Streamlit App │
│ localhost:8501 │ ← Beautiful web interface
└────────┬────────┘
│
▼
┌─────────────────┐
│ OpenAI API │
│ GPT-4 │ ← AI decides which tools to use
└────────┬────────┘
│
▼
┌─────────────────┐
│ MCP Server │
│ localhost:8000 │ ← Executes file operations
└────────┬────────┘
│
▼
┌─────────────────┐
│ workspace/ │
│ Your Files │ ← Safe sandbox folder
└─────────────────┘
🔧 Configuration
Basic Settings (.env)
# Required
OPENAI_API_KEY=sk-your-key-here
# Optional (defaults shown)
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8000
Advanced Settings (server/config.py)
# Change workspace location
WORKSPACE_DIR = Path("my_custom_folder")
# Change server port
MCP_SERVER_PORT = 9000
🐛 Troubleshooting
"Server Not Connected"
- Check if MCP server is running (Terminal 1)
- Click "Check Connection" button in sidebar
- Restart both server and Streamlit
"OpenAI API Key Error"
- Make sure
.envfile exists - Check your API key is correct
- Restart Streamlit after updating
.env
"Port Already in Use"
# Kill process on port 8000
lsof -i :8000
kill -9 <PID>
# Or change port in .env
MCP_SERVER_PORT=8001
"File Not Found"
Remember: All paths are relative to workspace/
✅ Correct: read_file("notes.txt")
❌ Wrong: read_file("workspace/notes.txt")
❌ Wrong: read_file("/absolute/path/file.txt")
🛠️ Development
Add a New Tool
Edit server/filesystem_mcp_server.py:
@mcp.tool()
def search_files(query: str) -> str:
"""
Search for files containing text.
Args:
query: Text to search for
Returns:
List of matching files
"""
# Your implementation here
return "Found 3 files matching 'query'"
Restart the server - that's it! The tool is automatically available.
🤝 Contributing
Contributions welcome! Here's how:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing) - Make your changes
- Test everything works
- Submit a pull request
🎓 Workshop Ready
This project is designed for learning and teaching:
- ✅ Clear, commented code
- ✅ Step-by-step setup
- ✅ Real-world example
- ✅ Production patterns
- ✅ Security best practices
Perfect for:
- Learning MCP architecture
- Building AI tools
- Teaching modern Python
- Prototyping ideas
Happy building! 🎉