Filesystem MCP With FastMCP Server
No description available
Ask AI about Filesystem MCP With FastMCP Server
Powered by Claude Β· Grounded in docs
I know everything about Filesystem MCP With FastMCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ποΈ 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! π
