Content
# MCP Workspace Server
**[English](./README_EN.md)** | **中文**
[](LICENSE)
🚀 **Just one MCP to realize your complete Agent capabilities!**
**AI Development Environment Beyond File Systems** - Enables AI to perform complete Web development, data processing, and code execution like Claude Code
> 💡 **Core Value**: No need to integrate multiple MCP tools, **one MCP server** can provide complete Agent capabilities such as file operations, code execution, Web deployment, data processing, and image generation. Out-of-the-box, one-stop solution.
A powerful MCP (Model Context Protocol) server that not only provides secure file system operations but also serves as a **complete AI development workspace**. It supports enterprise-level capabilities such as code execution, one-click Web application deployment, wildcard domain access, Excel processing, and image generation.
## ✨ Why Choose Us?
### 🎯 One MCP, Complete Agent Capabilities
**Traditional Solution**: Requires integrating multiple MCP tools to achieve full functionality
- ❌ File Operations → Requires one MCP
- ❌ Code Execution → Requires another MCP
- ❌ Web Deployment → Requires a third MCP
- ❌ Data Processing → Requires a fourth MCP
- ❌ Image Generation → Requires a fifth MCP
- **Result**: Complex configuration, difficult maintenance, fragmented functionality
**Our Solution**: Only one MCP is needed, all capabilities are available out-of-the-box
- ✅ **File Operations** + **Code Execution** + **Web Deployment** + **Data Processing** + **Image Generation**
- ✅ **Unified Configuration**: Configure once, enable all
- ✅ **Unified Management**: One service, centralized management
- ✅ **Unified Security**: One set of security policies, comprehensive protection
We provide a **complete AI development workspace**, with capabilities far beyond traditional file system servers:
- 🚀 **Web Development Capabilities**: AI can create complete Web applications (HTML/CSS/JS) and **deploy them to the production environment with one click**
- 🌐 **Wildcard Domain Deployment**: Supports `*.your-domain.com` wildcard domains, each session automatically gets independent subdomain access
- 💻 **Code Execution**: Built-in Python 3.12 and Node.js 20 sandbox environment, supports real-time code execution and debugging
- 📊 **Data Processing**: Complete Excel/CSV processing capabilities, supports templates, formulas, and formatting
- 🎨 **Image Generation**: Supports Mermaid flowcharts, data charts, HTML rendering, and other image generation methods
- 🔍 **Intelligent Search**: Advanced capabilities such as file content search, knowledge base retrieval, and web scraping
- 🔐 **Enterprise-Grade Security**: Multi-tenant isolation, path security protection, resource limits, sandbox execution
### 🎁 All-in-One Advantages
| Traditional Solution | Our Solution |
|---------|-----------|
| Requires 5+ MCP tools | **Only 1 MCP Needed** |
| Complex configuration, requires individual integration | **Out-of-the-box, one-click configuration** |
| Fragmented functionality, difficult to manage uniformly | **Centralized functionality, unified management** |
| Inconsistent security policies | **Unified security policy** |
| High maintenance costs | **Simple maintenance** |
**Summary in one sentence**: One MCP server = complete Agent capability stack 🚀
### 💡 Typical Use Cases
**Scenario 1: AI-Driven Web Development**
```
AI creates a complete front-end application → One-click deployment → Get independent domain access
For example: https://user123_chat456.your-domain.com
```
**Scenario 2: Data Analysis and Visualization**
```
Read Excel → Data processing → Generate charts → Create reports → Deploy a display page
```
**Scenario 3: Code Development and Testing**
```
Write Python script → Execute tests → Fix bugs → Deploy API service
```
## ✨ Core Features
### 🔐 Multi-Tenant Session Isolation
Each user/session has an independent virtual workspace, completely isolated and non-interfering.
**Working Directory Naming Rules:**
| X-User-ID | X-Chat-ID | Working Directory |
|----------|-----------|----------|
| `user123` | `chat456` | `user_data/user123_chat456/` |
| `user123` | (empty) | `user_data/user123/` |
| (empty) | `chat456` | `user_data/chat456/` |
| (empty) | (empty) | Use default global mode |
Pass identity information through HTTP request headers:
- `X-User-ID`: Unique user identifier (optional)
- `X-Chat-ID`: Unique session identifier (optional)
### 🛡️ Virtual Path System
**LLM Perspective is Completely Virtualized**: The AI model sees a clean virtual file system with `/` as the root directory.
```
Path Seen by LLM Actual Physical Path
─────────────────────────────────────────────────────────
/ → /server/user_data/user123_chat456/
/todo.txt → /server/user_data/user123_chat456/todo.txt
/docs/readme.md → /server/user_data/user123_chat456/docs/readme.md
```
**Advantages:**
- ✅ Does not expose the server's real directory structure
- ✅ AI platform cannot obtain physical path information
- ✅ Simplifies AI file operation instructions
- ✅ Improves security and privacy protection
### 🔒 Path Security Protection
Built-in multi-layer security mechanisms to prevent path traversal attacks:
```
Attack Attempt Result
─────────────────────────────────────────────────
/../../../etc/passwd ❌ Blocked
../../../etc/passwd ❌ Blocked
/foo/../../../etc/passwd ❌ Blocked
/foo/bar/../../.. ❌ Blocked
```
**Security Mechanisms:**
1. **Path Resolution**: Use `Path.resolve()` to resolve all `..` and symbolic links
2. **Boundary Check**: Verify that the resolved path is within the allowed range
3. **Double Protection**: Even if the path is resolved, it must still be within `allowed_dirs`
### 📡 SSE Transport Protocol
Supports Server-Sent Events (SSE) transport, adapted to various AI platforms:
```
Client Server
│ │
│──── GET /sse ──────────────────────▶│ Establish SSE connection
│◀─── SSE: endpoint=/messages?sid=xxx │ Return message endpoint
│ │
│──── POST /messages?session_id=xxx ─▶│ Send tool call
│◀─── SSE: message (response) ───────────│ Receive result
```
### 🌐 One-Click Deployment and Wildcard Domain Support
**One-Click Deployment of Web Applications**:
- Front-end projects created by AI can be deployed with one click using the `preview_frontend` tool
- Automatically generate accessible URLs, supports HTTPS
- Supports custom entry files and directory structures
**Wildcard Domain Deployment (Production Environment)**:
```json
{
"preview": {
"wildcard_domain": "*.proxy.your-domain.com",
"use_tls": true
}
}
```
After configuration, each session automatically gets an independent subdomain:
- `user123_chat456.proxy.your-domain.com`
- `user789_chat012.proxy.your-domain.com`
**Advantages**:
- ✅ No need to manually configure domain names and ports
- ✅ Automatic isolation, no interference
- ✅ Supports HTTPS, production-ready
- ✅ Single-port service, simplifies deployment
## 📦 Complete Feature List
### 💻 Web Development and Deployment
| Tool | Function | Highlights |
|------|------|------|
| `fs_write` | Create Web files (HTML/CSS/JS) | Automatically recognizes format, supports complete front-end projects |
| `preview_frontend` | One-click deployment of static front-end | **Supports wildcard domains, automatically generates independent subdomains** |
| `exec` | Execute Python/Node.js code | Sandbox environment, supports real-time debugging |
| `generate_image` | Generate charts and flowcharts | Mermaid, data visualization, HTML rendering |
### 📁 File System Operations
| Tool | Function |
|------|------|
| `fs_read` | Read files (supports batch, Excel, row range) |
| `fs_write` | Create/overwrite files (automatically recognizes format) |
| `fs_ops` | File system operations (list/mkdir/move/info/delete) |
| `fs_replace` | Precisely edit files based on SEARCH/REPLACE |
| `fs_search` | Search files (glob=by filename, content=by content regex) |
### 📊 Excel Data Processing
| Tool | Function |
|------|------|
| `fs_read` | Read Excel files (supports sheet, range parameters) |
| `fs_write` | Create/overwrite Excel files (automatically recognizes format) |
| `excel_edit` | Edit Excel (batch update cells, formatting) |
| `list_excel_templates` | List available Excel templates |
| `create_excel_from_template` | Create Excel files from templates |
### 🔍 Advanced Capabilities (Optional)
| Tool | Function | Configuration Item |
|------|------|--------|
| `kb_search` | Enterprise knowledge base glob search | `kb.enabled=true` |
| `kb_read` | Read knowledge base files (returns Markdown) | `kb.enabled=true` |
| `crawl_url` | Crawl web pages and return Markdown | `web_crawl.enabled=true` |
| `web_search` | Web search | `web_search.enabled=true` |
## 🔌 Integration with AI Platforms
### 🎯 Why Choose Us as Your MCP Server?
**We are a powerful All-in-One MCP Server**, configure once to provide complete Agent capabilities for your AI platform:
- ✅ **File Operations**: Read, write, search, and edit files
- ✅ **Code Execution**: Python/Node.js sandbox environment
- ✅ **Web Deployment**: One-click deployment of front-end applications, supports wildcard domains
- ✅ **Data Processing**: Complete Excel/CSV processing capabilities
- ✅ **Image Generation**: Mermaid flowcharts, data charts
- ✅ **Intelligent Search**: Knowledge base retrieval, web scraping (optional)
**No need to integrate multiple MCP tools**, one MCP Server can meet all needs!
### 🚀 Supported AI Platforms
We integrate perfectly with mainstream AI platforms, easy to configure, and ready to use:
#### Dify
1. **Enter Dify Workflow Configuration**
- Add **MCP Tool** node
- Select **SSE** transport protocol
2. **Configure MCP Server Connection**
```
SSE Address: http://your-server:8000/sse
```
3. **Set Request Headers (Multi-Tenant Isolation)**
```
X-User-ID: {{user_id}}
X-Chat-ID: {{conversation_id}}
```
4. **Done!** Now your Dify Agent has complete file operation, code execution, Web deployment, and other capabilities.
#### FastGPT
1. **Enter FastGPT Knowledge Base/Application Configuration**
- Add **External Tool** → **MCP**
- Select **SSE** for transport method
2. **Configure Connection Information**
```
MCP Server URL: http://your-server:8000/sse
```
3. **Configure User Identification (Optional, for Multi-Tenant Isolation)**
```
Custom Header:
X-User-ID: {{userId}}
X-Chat-ID: {{chatId}}
```
4. **Enable Tools**: All tools are automatically available, no need to configure them individually!
#### Cherry Studio
1. **Enter Cherry Studio Settings**
- Open **MCP Servers** configuration
- Add a new MCP Server
2. **Configure Connection**
```json
{
"name": "MCP Workspace Server",
"transport": "sse",
"url": "http://your-server:8000/sse"
}
```
3. **Set Session Identification (Multi-Tenant Support)**
- Cherry Studio automatically passes user and session information
- Each session gets an independent workspace
### 💡 Integration Advantages
| Traditional Solution | Using Our All-in-One MCP |
|---------|---------------------------|
| Requires configuring 5+ different MCP tools | **Only need to configure 1 MCP Server** |
| Each tool requires separate connection and authentication | **Configure once, enable all** |
| Functionality is fragmented between tools, difficult to manage uniformly | **Centralized functionality, unified management** |
| Inconsistent security policies between different tools | **Unified security policy, comprehensive protection** |
| High cost of maintaining multiple services | **Simple maintenance, one service does it all** |
### 🎁 Out-of-the-Box Capabilities
After configuration, your AI Agent immediately has:
- 📝 **File Operations**: Create, read, edit, search files
- 💻 **Code Execution**: Run Python/Node.js scripts, real-time debugging
- 🌐 **Web Development**: Create front-end applications and deploy them to the production environment with one click
- 📊 **Data Processing**: Read, edit Excel, generate reports
- 🎨 **Image Generation**: Create flowcharts, data visualization charts
- 🔍 **Intelligent Search**: File content search, knowledge base retrieval (if enabled)
**One MCP Server = Complete Agent Capability Stack** 🚀
## 🚀 Quick Start
### Docker Deployment (Recommended)
```bash
# Clone the project
git clone <repository-url>
cd mcp-filesystem
# First deployment: build the image and start
docker-compose up -d --build
> If you cannot use the docker image source, you can execute export DOCKER_BUILDKIT=0 first
# Restart to take effect after updating the code
git pull && docker-compose restart
# View logs
docker-compose logs -f
# Rebuild only when dependencies change
docker-compose up -d --build
```
> 💡 The image contains the runtime environment, the code is mounted through volume, updating the code only requires `git pull && docker-compose restart`
> ⚠️ **Important Note**: The running environment of this project is highly dependent on the Docker base image, which includes a complete Python 3.12, Node.js 20 runtime environment, and all system dependencies (such as Tesseract OCR, image processing libraries, etc.). **It is strongly recommended to deploy using Docker**, and it is not recommended to run Python directly locally. If you need local development, please ensure that all system dependencies are installed.
### Quick Configuration Reference
> 📖 **Detailed Integration Instructions**: Please see the [🔌 Integration with AI Platforms](#-与-ai-平台集成) section above, which includes complete configuration steps for Dify, FastGPT, and Cherry Studio.
**Quick Connection Information**:
- **SSE Address**: `http://your-server:8000/sse`
- **Request Headers** (Multi-Tenant Isolation):
- `X-User-ID`: `{{userId}}` or fixed user ID
- `X-Chat-ID`: `{{chatId}}` or fixed session ID
**Claude Desktop (STDIO Mode)**:
Edit the configuration file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"mcp-workspace": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp-filesystem",
"run",
"run_server.py",
"/path/to/allowed/dir1",
"/path/to/allowed/dir2"
]
}
}
}
```
## 🏗️ Architecture Design
```
┌─────────────────────────────────────────────────────────────┐
│ AI 平台 (Dify / FastGPT / Cherry Studio) │
└─────────────────────────────────────────────────────────────┘
│
│ SSE + HTTP POST
│ Headers: X-User-ID, X-Chat-ID
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP Workspace Server (All-in-One) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 会话管理 & 身份识别 │ │
│ │ (user_id + chat_id → workspace_name) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 虚拟路径转换层 │ │
│ │ /todo.txt → /user_data/xxx/todo.txt │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 路径安全验证 │ │
│ │ PathValidator + 路径遍历防护 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 文件操作执行 │ │
│ │ FileOperations / AdvancedFileOperations │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 物理文件系统 │
│ user_data/ │
│ ├── user1_chat1/ │
│ │ ├── todo.txt │
│ │ └── docs/ │
│ ├── user1_chat2/ │
│ └── user2_chat1/ │
└─────────────────────────────────────────────────────────────┘
```
## 🔧 Admin API
Provides HTTP interfaces for monitoring, debugging, and operations.
### 🔑 Authentication Configuration
Admin API requires Bearer Token authentication. First, configure `config.json`:
```bash
# Copy the example configuration file
cp config.example.json config.json
# Edit the configuration, setting your admin key
vim config.json
```
```json
{
"admin_token": "your-secret-admin-token-here"
}
```
All Admin API requests must carry the `Authorization` header:
```bash
curl -H "Authorization: Bearer your-secret-admin-token-here" \
http://localhost:8000/admin/stats
```
> ⚠️ **Security Tip**: `config.json` has been added to `.gitignore`. Do not commit it to the repository.
### Get Server Statistics
```http
GET /admin/stats
Authorization: Bearer <admin_token>
```
**Response Example:**
```json
{
"success": true,
"user_data_dir": "/path/to/user_data",
"total_workspaces": 15,
"unique_users": 8,
"total_size_bytes": 1048576,
"total_size_human": "1.00 MB",
"active_sessions": 3
}
```
### List All Workspaces
```http
GET /admin/workspaces
GET /admin/workspaces?user_id=user123
Authorization: Bearer <admin_token>
```
### Get Workspace Details
```http
GET /admin/workspace/{workspace_id}
GET /admin/workspace/{workspace_id}/tree?max_depth=5
Authorization: Bearer <admin_token>
```
### Delete Workspace
```http
DELETE /admin/workspace/{workspace_id}?confirm=yes
Authorization: Bearer <admin_token>
```
⚠️ **Warning**: This operation is irreversible! You must add the `?confirm=yes` parameter to perform the deletion.
## 👤 User Workspace API
Provides users with workspace directory tree queries without the need for an admin token.
```http
GET /api/workspace/tree?user_id={user_id}&chat_id={chat_id}&max_depth=5
```
- No `Authorization` header is required
- Only returns the workspace corresponding to the `user_id + chat_id` combination
- Each directory level is sorted by the most recent modification time, retaining only the top 20 files/folders, with the rest filtered directly to save bandwidth
## 🧩 Excel Configuration
- `config.json`/`config.example.json` adds an `excel` section for setting the maximum file size, default number of rows to read, supported formats, and formula detection switch.
- Template: `excel.templates_file` defaults to `excel_templates/templates.json`. Template source files are placed in `excel_templates/`, exposing only `title/desc`. `create_excel_from_template` automatically avoids duplicate names. For first-time use, copy and create `templates.json` from `templates_example.json` and configure the template path according to the actual situation.
- Environment variable overrides: `MCP_EXCEL_MAX_ROWS`, `MCP_EXCEL_MAX_SIZE_MB`.
- See `docs/EXCEL_TOOLS.md` for detailed parameters and examples.
## ⚙️ Startup Configuration
- A new `mcp` section has been added to `config.json`, which can configure `transport` (default `sse`), `host` (default `0.0.0.0`), and `port` (default `18089`).
- CLI parameters `--transport/--host/--port` have higher priority than the configuration file.
- Web Management Interface: `config.json` adds an `admin_web` section (`enabled` defaults to `false`, `password` defaults to `123456`). After enabling, visit `http://<host>:<port>/admin`, enter the password to view the file tree under user_data and preview text/Markdown/CSV.
## 📖 Usage Examples
### 🚀 Complete Web Development Process
**Step 1: Create a Frontend Project**
```
Tool: fs_write
Arguments: {
"path": "/index.html",
"content": "<!DOCTYPE html>..."
}
```
**Step 2: One-Click Deployment**
```
Tool: preview_frontend
Arguments: {
"entry_file": "index.html"
}
```
**Return Result**:
```json
{
"success": true,
"url": "https://user123_chat456.proxy.your-domain.com/index.html",
"subdomain": "user123_chat456"
}
```
**Step 3: Access the Deployed Application**
- Automatically obtain an independent subdomain
- Supports HTTPS (if configured)
- No need to manually configure ports and domains
### 💻 Code Execution and Debugging
### Read File (Supports Line Range)
```
Tool: fs_read
Arguments: {
"path": "/file.txt",
"line_range": "100:150" # Read lines 100-150
}
```
### Batch Read Files
```
Tool: fs_read
Arguments: {
"path": ["/file1.txt", "/file2.json", "/data.xlsx"]
}
```
### Search Files
```
Tool: fs_search
Arguments: {
"search_type": "content", # glob=by filename, content=by content
"pattern": "function\\s+\\w+\\(",
"context_lines": 2 # Return 2 lines of context before and after the matching line
}
```
### Precisely Edit Files
```
Tool: fs_replace
Arguments: {
"path": "/config.py",
"diff": "------- SEARCH\nDEBUG = True\n========\nDEBUG = False\n+++++++ REPLACE"
}
```
### Execute Python Code
```
Tool: exec
Arguments: {
"code": "print('Hello, World!')"
}
```
### Execute Python File
```
Tool: exec
Arguments: {
"file": "/script.py",
"args": ["--verbose", "input.txt"]
}
```
### Read Excel File
```
Tool: fs_read
Arguments: {
"path": "/data.xlsx",
"sheet": "Sheet1", # Optional, specify the worksheet
"range": "A1:D100" # Optional, specify the reading range
}
```
### Create Excel File
```
Tool: fs_write
Arguments: {
"path": "/output.xlsx",
"content": [
["Name", "Age", "City"],
["Alice", 30, "Beijing"],
["Bob", 25, "Shanghai"]
]
}
```
### Edit Excel File
```
Tool: excel_edit
Arguments: {
"path": "/data.xlsx",
"edit_type": "cells",
"sheet": "Sheet1",
"updates": [
{"cell": "A1", "value": "Updated Value"}
]
}
```
### 🎨 Generate Charts and Flowcharts
```
Tool: generate_image
Arguments: {
"mermaid_code": "flowchart TD\nA[开始] --> B[处理] --> C[结束]"
}
```
Or use HTML to render complex charts:
```
Tool: generate_image
Arguments: {
"html_code": "<html><body><h1>数据可视化</h1>...</body></html>"
}
```
## 🔐 Security Best Practices
1. **Production Environment Deployment**
- Use a reverse proxy (Nginx) to handle HTTPS
- Restrict access IP or use API key authentication
- Set reasonable request rate limits
2. **Data Isolation**
- Ensure that `X-User-ID` and `X-Chat-ID` are generated by a trusted source
- Regularly clean up expired session working directories
3. **Admin API Protection**
```nginx
location /admin/ {
allow 10.0.0.0/8;
deny all;
proxy_pass http://localhost:8000;
}
```
## ⚙️ Environment Variables
| Variable Name | Description | Default Value |
|---------------|-------------|---------------|
| `MCP_WORKSPACES_DIR` | Root directory for user workspaces | `项目目录/user_data` |
| `MCP_ALLOWED_DIRS` | List of allowed directories (global pattern) | Current working directory |
| `FASTMCP_PORT` | Server port | `8000` |
## 📄 License
[Apache License 2.0](LICENSE)
## 🤝 Contribution
Welcome to submit Issues and Pull Requests!
