MCP Workspace Server

English | 中文

🚀 One MCP, Complete Agent Capabilities!

Beyond Filesystem - Complete AI Development Environment - Enable AI to perform full-stack Web development, data processing, and code execution like Claude Code

💡 Core Value: No need to integrate multiple MCP tools. One MCP server provides complete Agent capabilities including file operations, code execution, web deployment, data processing, and image generation. Ready to use out of the box, an all-in-one solution.

A powerful MCP (Model Context Protocol) server that goes far beyond file system operations. It's a complete AI development workspace with code execution, one-click web deployment, wildcard domain support, Excel processing, image generation, and enterprise-grade capabilities.

✨ Why Choose Us?

🎯 One MCP, Complete Agent Capabilities

Traditional Approach: Need to integrate multiple MCP tools to achieve full functionality

❌ File operations → Need one MCP
❌ Code execution → Need another MCP
❌ Web deployment → Need a third MCP
❌ Data processing → Need a fourth MCP
❌ Image generation → Need a fifth MCP
Result: Complex configuration, difficult maintenance, scattered functionality

Our Approach: Just one MCP, all capabilities ready 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 security policy, comprehensive protection

We provide a complete AI development workspace with capabilities far beyond traditional filesystem servers:

🚀 Web Development: AI can create full web applications (HTML/CSS/JS) and deploy them to production with one click
🌐 Wildcard Domain Deployment: Support *.your-domain.com wildcard domains, each session automatically gets its own subdomain
💻 Code Execution: Built-in Python 3.12 and Node.js 20 sandbox environments for real-time code execution and debugging
📊 Data Processing: Complete Excel/CSV processing with templates, formulas, and formatting
🎨 Image Generation: Multiple image generation methods including Mermaid flowcharts, data charts, and HTML rendering
🔍 Smart Search: Advanced capabilities like file content search, knowledge base retrieval, and web crawling
🔐 Enterprise Security: Multi-tenant isolation, path security protection, resource limits, and sandbox execution

🎁 All-in-One Advantages

Traditional Approach	Our Approach
Need 5+ MCP tools	Just 1 MCP
Complex configuration, need to integrate one by one	Ready out of the box, one-click configuration
Scattered functionality, hard to manage	Centralized functionality, unified management
Inconsistent security policies	Unified security policy
High maintenance cost	Simple maintenance

In One Sentence: One MCP server = Complete Agent capability stack 🚀

💡 Typical Use Cases

Use Case 1: AI-Driven Web Development

AI creates full frontend app → One-click deployment → Gets independent domain access
Example: https://user123_chat456.your-domain.com

Use Case 2: Data Analysis & Visualization

Read Excel → Data processing → Generate charts → Create reports → Deploy showcase page

Use Case 3: Code Development & Testing

Write Python scripts → Execute tests → Fix bugs → Deploy API services

✨ Key Features

🔐 Multi-Tenant Session Isolation

Each user/session has an independent virtual workspace, completely isolated from others.

Workspace Naming Convention:

X-User-ID	X-Chat-ID	Workspace Directory
`user123`	`chat456`	`user_data/user123_chat456/`
`user123`	(empty)	`user_data/user123/`
(empty)	`chat456`	`user_data/chat456/`
(empty)	(empty)	Uses default global mode

Pass identity via HTTP headers:

X-User-ID: User unique identifier (optional)
X-Chat-ID: Session unique identifier (optional)

🛡️ Virtual Path System

Fully Virtualized LLM Perspective: AI models see a clean virtual filesystem with / as the root.

LLM's View                  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

Benefits:

✅ Does not expose real server directory structure
✅ AI platforms cannot access physical path information
✅ Simplifies AI file operation commands
✅ Enhanced 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:

Path Resolution: Uses Path.resolve() to resolve all .. and symlinks
Boundary Check: Validates that resolved paths are within allowed scope
Double Protection: Even after resolution, paths must be within allowed_dirs

📡 SSE Transport Protocol

Supports Server-Sent Events (SSE) transport, compatible with 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 calls
   │◀─── SSE: message (response) ───────│  Receive results

🌐 One-Click Deployment & Wildcard Domain Support

One-Click Web Deployment:

Frontend projects created by AI can be deployed with one click via preview_frontend tool
Automatically generates accessible URLs with HTTPS support
Supports custom entry files and directory structures

Wildcard Domain Deployment (Production):

{
  "preview": {
    "wildcard_domain": "*.proxy.your-domain.com",
    "use_tls": true
  }
}

After configuration, each session automatically gets its own subdomain:

user123_chat456.proxy.your-domain.com
user789_chat012.proxy.your-domain.com

Benefits:

✅ No manual domain or port configuration needed
✅ Automatic isolation, no interference
✅ HTTPS support, production-ready
✅ Single-port service, simplified deployment

📦 Complete Feature List

💻 Web Development & Deployment

Tool	Feature	Highlight
`fs_write`	Create web files (HTML/CSS/JS)	Auto-detects format, supports full frontend projects
`preview_frontend`	One-click static frontend deployment	Supports wildcard domains, auto-generates unique 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	Description
`fs_read`	Read files (supports batch, Excel, line ranges)
`fs_write`	Create/overwrite files (auto-detects format)
`fs_ops`	File system operations (list/mkdir/move/info/delete)
`fs_replace`	Precise file editing using SEARCH/REPLACE diff syntax
`fs_search`	Search files (glob=by filename, content=by content regex)

📊 Excel Data Processing

Tool	Description
`fs_read`	Read Excel files (supports sheet, range parameters)
`fs_write`	Create/overwrite Excel files (auto-detects format)
`excel_edit`	Edit Excel (batch update cells, formatting)
`list_excel_templates`	List available Excel templates
`create_excel_from_template`	Create Excel file from template

🔍 Advanced Capabilities (Optional)

Tool	Description	Config
`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. With just one configuration, you can provide complete Agent capabilities to your AI platform:

✅ File Operations: Read, write, search, and edit files
✅ Code Execution: Python/Node.js sandbox environment
✅ Web Deployment: One-click frontend deployment with wildcard domain support
✅ Data Processing: Complete Excel/CSV processing capabilities
✅ Image Generation: Mermaid flowcharts, data charts
✅ Smart Search: Knowledge base retrieval, web crawling (optional)

No need to integrate multiple MCP tools - one MCP Server meets all your needs!

🚀 Supported AI Platforms

We integrate seamlessly with mainstream AI platforms, simple configuration, ready out of the box:

Dify

Go to Dify Workflow Configuration
- Add MCP Tool node
- Select SSE transport protocol

Configure MCP Server Connection

SSE Address: http://your-server:8000/sse

Set Request Headers (Multi-tenant Isolation)

X-User-ID: {{user_id}}
X-Chat-ID: {{conversation_id}}

Done! Your Dify Agent now has complete file operations, code execution, web deployment capabilities.

FastGPT

Go to FastGPT Knowledge Base/App Configuration
- Add External Tool → MCP
- Select SSE transport method

Configure Connection Information

MCP Server URL: http://your-server:8000/sse

Configure User Identity (Optional, for multi-tenant isolation)
```
Custom Header:
X-User-ID: {{userId}}
X-Chat-ID: {{chatId}}
```
Enable Tools: All tools are automatically available, no need to configure one by one!

Cherry Studio

Go to Cherry Studio Settings
- Open MCP Servers configuration
- Add new MCP Server

Configure Connection

{
  "name": "MCP Workspace Server",
  "transport": "sse",
  "url": "http://your-server:8000/sse"
}

Set Session Identity (Multi-tenant Support)
- Cherry Studio automatically passes user and session information
- Each session gets an independent workspace

💡 Integration Advantages

Traditional Approach	Using Our All-in-One MCP
Need to configure 5+ different MCP tools	Just configure 1 MCP Server
Each tool requires separate connection and authentication	Configure once, enable all
Scattered functionality, hard to manage	Centralized functionality, unified management
Inconsistent security policies across tools	Unified security policy, comprehensive protection
High maintenance cost for multiple services	Simple maintenance, one service handles all

🎁 Ready-to-Use 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 frontend apps and deploy to production with one click
📊 Data Processing: Read, edit Excel, generate reports
🎨 Image Generation: Create flowcharts, data visualization charts
🔍 Smart Search: File content search, knowledge base retrieval (if enabled)

One MCP Server = Complete Agent Capability Stack 🚀

🚀 Quick Start

Docker Deployment (Recommended)

# Clone the project
git clone <repository-url>
cd mcp-filesystem

# First deployment: build image and start
docker-compose up -d --build

# After code updates, restart to apply
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; code is mounted via volume. To update, just git pull && docker-compose restart

⚠️ Important: This project's runtime environment heavily depends 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.). Docker deployment is strongly recommended; local Python execution is not recommended. For local development, ensure all system dependencies are installed.

Quick Configuration Reference

📖 Detailed Integration Guide: Please refer to the 🔌 Integration with AI Platforms section above for complete configuration steps for Dify, FastGPT, and Cherry Studio.

Quick Connection Info:

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 config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.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

┌─────────────────────────────────────────────────────────────┐
│        AI Platforms (Dify / FastGPT / Cherry Studio)        │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ SSE + HTTP POST
                              │ Headers: X-User-ID, X-Chat-ID
                              ▼
┌─────────────────────────────────────────────────────────────┐
│            MCP Workspace Server (All-in-One)                 │
│  ┌─────────────────────────────────────────────────────────┐│
│  │           Session Management & Identity Recognition      ││
│  │         (user_id + chat_id → workspace_name)            ││
│  └─────────────────────────────────────────────────────────┘│
│                              │                               │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              Virtual Path Translation Layer              ││
│  │         /todo.txt → /user_data/xxx/todo.txt             ││
│  └─────────────────────────────────────────────────────────┘│
│                              │                               │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              Path Security Validation                    ││
│  │         PathValidator + Traversal Protection             ││
│  └─────────────────────────────────────────────────────────┘│
│                              │                               │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              File Operation Execution                    ││
│  │         FileOperations / AdvancedFileOperations          ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Physical Filesystem                     │
│  user_data/                                                 │
│  ├── user1_chat1/                                           │
│  │   ├── todo.txt                                           │
│  │   └── docs/                                              │
│  ├── user1_chat2/                                           │
│  └── user2_chat1/                                           │
└─────────────────────────────────────────────────────────────┘

🔧 Admin API

HTTP endpoints for monitoring, debugging, and operations.

🔑 Authentication Configuration

Admin API requires Bearer Token authentication. First configure config.json:

# Copy the example config file
cp config.example.json config.json

# Edit config and set your admin secret
vim config.json

{
  "admin_token": "your-secret-admin-token-here"
}

All Admin API requests must include the Authorization header:

curl -H "Authorization: Bearer your-secret-admin-token-here" \
     http://localhost:8000/admin/stats

⚠️ Security Note: config.json is added to .gitignore. Do not commit it to version control.

Get Server Statistics

GET /admin/stats
Authorization: Bearer <admin_token>

Response Example:

{
  "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

GET /admin/workspaces
GET /admin/workspaces?user_id=user123
Authorization: Bearer <admin_token>

Get Workspace Details

GET /admin/workspace/{workspace_id}
GET /admin/workspace/{workspace_id}/tree?max_depth=5
Authorization: Bearer <admin_token>

Delete Workspace

DELETE /admin/workspace/{workspace_id}?confirm=yes
Authorization: Bearer <admin_token>

⚠️ Warning: This operation is irreversible! The ?confirm=yes parameter is required.

👤 User Workspace API

Fetch a workspace tree for a specific user/chat without the admin token.

GET /api/workspace/tree?user_id={user_id}&chat_id={chat_id}&max_depth=5

No Authorization header required
Scope is limited to the workspace derived from user_id + chat_id
Each directory only returns the 20 most recently modified items (files or subfolders) to keep responses lightweight

🧩 Excel Settings

config.json/config.example.json now include an excel block for max file size, default read rows, supported formats, and formula scanning toggle.
Templates: excel.templates_file defaults to excel_templates/templates.json, with template sources stored in excel_templates/. Only title/desc are exposed to clients; create_excel_from_template copies the source and auto-avoids name conflicts. On first use, copy templates_example.json to create templates.json and configure template paths according to your actual setup.
Environment overrides: MCP_EXCEL_MAX_ROWS, MCP_EXCEL_MAX_SIZE_MB.
See docs/EXCEL_TOOLS.md for tool arguments and examples.

⚙️ Startup Settings

config.json now includes an mcp block to set transport (default sse), host (default 0.0.0.0), and port (default 18089).
CLI flags --transport/--host/--port override config values.
Web admin UI: config.json adds an admin_web block (enabled default false, password default 123456). When enabled, open http://<host>:<port>/admin, enter the password, and browse the user_data tree with inline previews for text/Markdown/CSV.

📖 Usage Examples

🚀 Complete Web Development Workflow

Step 1: Create 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"
}

Response:

{
  "success": true,
  "url": "https://user123_chat456.proxy.your-domain.com/index.html",
  "subdomain": "user123_chat456"
}

Step 3: Access Deployed Application

Automatically gets unique subdomain
Supports HTTPS (if configured)
No manual port or domain configuration needed

💻 Code Execution & Debugging

Read File (with 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 around matches
}

Precise File Editing

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 worksheet
  "range": "A1:D100"      # Optional, specify 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[Start] --> B[Process] --> C[End]"
}

Or use HTML rendering for complex charts:

Tool: generate_image
Arguments: {
  "html_code": "<html><body><h1>Data Visualization</h1>...</body></html>"
}

🔐 Security Best Practices

Production Deployment
- Use reverse proxy (Nginx) for HTTPS
- Restrict access by IP or use API key authentication
- Set reasonable rate limits
Data Isolation
- Ensure X-User-ID and X-Chat-ID are generated from trusted sources
- Regularly clean up expired session workspaces

Admin API Protection

location /admin/ {
    allow 10.0.0.0/8;
    deny all;
    proxy_pass http://localhost:8000;
}

⚙️ Environment Variables

Variable	Description	Default
`MCP_WORKSPACES_DIR`	User workspace root directory	`project_dir/user_data`
`MCP_ALLOWED_DIRS`	Allowed directories list (global mode)	Current working directory
`FASTMCP_PORT`	Server port	`8000`

📄 License

Apache License 2.0

🤝 Contributing

Issues and Pull Requests are welcome!

FilesExpand file tree

README_EN.md

Latest commit

History