MCP Workspace Server

🚀 MCP Workspace Server

Achieve full Agent capabilities with just one MCP!

The MCP Workspace Server is an AI development environment that goes beyond the traditional file system. It enables comprehensive web development, data processing, and code execution, similar to what Claude Code can do.

💡 Core Value: Instead of integrating multiple MCP tools, a single MCP server provides complete Agent capabilities, including file operations, code execution, web deployment, data processing, and image generation. It's an out-of-the-box, one-stop solution.

This powerful MCP (Model Context Protocol) server not only offers 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.

🚀 Quick Start

Docker Deployment (Recommended)

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

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

> If you can't use the Docker image source, run export DOCKER_BUILDKIT=0 first.

# Restart after code updates
git pull && docker-compose restart

# View logs
docker-compose logs -f

# Rebuild only when dependencies change
docker-compose up -d --build

💡 The image includes the runtime environment, and the code is mounted via volume. You can update the code with git pull && docker-compose restart.

⚠️ Important Note: This project highly depends on the Docker base image, which includes a complete Python 3.12, Node.js 20 runtime environment, and all system dependencies (e.g., Tesseract OCR, image processing libraries). We strongly recommend using Docker for deployment. Running directly with local Python is not recommended. If you need local development, make sure all system dependencies are installed.

Quick Configuration Reference

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

Quick Connection Information:

• SSE Address: http://your-server:8000/sse
• Request Headers (for multi-tenant isolation):
  • X-User-ID: {{userId}} or a fixed user ID
  • X-Chat-ID: {{chatId}} or a 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

{
  "mcpServers": {
    "mcp-workspace": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-filesystem",
        "run",
        "run_server.py",
        "/path/to/allowed/dir1",
        "/path/to/allowed/dir2"
      ]
    }
  }
}

✨ Features

🎯 One MCP, Full Agent Capabilities

Traditional Approach: Multiple MCP tools need to be integrated to achieve full functionality.

• ❌ File operations → One MCP required
• ❌ Code execution → Another MCP required
• ❌ Web deployment → A third MCP required
• ❌ Data processing → A fourth MCP required
• ❌ Image generation → A fifth MCP required
• Result: Complex configuration, difficult maintenance, and scattered functionality.

Our Approach: One MCP provides all capabilities 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 offer a complete AI development workspace with capabilities far beyond traditional file system servers:

• 🚀 Web Development: 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 an independent subdomain for access.
• 💻 Code Execution: Built-in Python 3.12 and Node.js 20 sandbox environments support real-time code execution and debugging.
• 📊 Data Processing: Full Excel/CSV processing capabilities, supporting templates, formulas, and formatting.
• 🎨 Image Generation: Supports various image generation methods such as Mermaid flowcharts, data charts, and HTML rendering.
• 🔍 Intelligent Search: Advanced capabilities such as file content search, knowledge base retrieval, and web page scraping.
• 🔐 Enterprise-Level Security: Multi-tenant isolation, path security protection, resource limits, and sandbox execution.

🎁 All-in-One Advantages

In a nutshell: One MCP server = A complete Agent capability stack 🚀

💡 Typical Use Cases

Case 1: AI-Driven Web Development

AI creates a complete front-end application → One-click deployment → Get an independent domain for access
Example: https://user123_chat456.your-domain.com

Case 2: Data Analysis and Visualization

Read Excel → Data processing → Generate charts → Create reports → Deploy a presentation page

Case 3: Code Development and Testing

Write a Python script → Execute tests → Fix bugs → Deploy an API service

🔐 Multi-Tenant Session Isolation

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

Working Directory Naming Rules:

Pass the identity information through HTTP request headers:

• X-User-ID: Unique user identifier (optional)
• X-Chat-ID: Unique session identifier (optional)

🛡️ Virtual Path System

Completely Virtual from the LLM Perspective: The AI model sees a clean virtual file system with / as the root directory.

LLM-Visible Path          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 real directory structure of the server.
• ✅ The AI platform cannot obtain physical path information.
• ✅ Simplifies file operation instructions for AI.
• ✅ Improves security and privacy protection.

🔒 Path Security Protection

Built-in multi-layer security mechanisms 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 Transmission Protocol

Supports Server-Sent Events (SSE) transmission, compatible with various AI platforms:

Client                                Server
   │                                    │
   │──── GET /sse ──────────────────────▶│  Establish an SSE connection
   │◀─── SSE: endpoint=/messages?sid=xxx │  Return the message endpoint
   │                                    │
   │──── POST /messages?session_id=xxx ─▶│  Send a tool call
   │◀─── SSE: message (Response) ───────│  Receive the 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 an accessible URL, supporting HTTPS.
• Supports custom entry files and directory structures.

Wildcard Domain Deployment (Production Environment):

{
  "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 domains and ports.
• ✅ Automatic isolation, no interference.
• ✅ Supports HTTPS, ready for production.
• ✅ Single-port service, simplifies deployment.

📦 Installation

Docker Deployment (Recommended)

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

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

> If you can't use the Docker image source, run export DOCKER_BUILDKIT=0 first.

# Restart after code updates
git pull && docker-compose restart

# View logs
docker-compose logs -f

# Rebuild only when dependencies change
docker-compose up -d --build

💻 Usage Examples

🚀 Complete Web Development Process

Step 1: Create a Front-End 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:

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

Step 3: Access the Deployed Application

• Automatically get an independent subdomain.
• Supports HTTPS (if configured).
• No need to manually configure ports and domains.

💻 Code Execution and Debugging

Read a File (Supporting Line Range)

Tool: fs_read
Arguments: {
  "path": "/file.txt",
  "line_range": "100:150"  # Read lines 100-150
}

Read Multiple Files in Bulk

Tool: fs_read
Arguments: {
  "path": ["/file1.txt", "/file2.json", "/data.xlsx"]
}

Search for Files

Tool: fs_search
Arguments: {
  "search_type": "content",  # glob=By file name, content=By content
  "pattern": "function\\s+\\w+\\(",
  "context_lines": 2  # Return 2 lines of context before and after the matching line
}

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 a Python File

Tool: exec
Arguments: {
  "file": "/script.py",
  "args": ["--verbose", "input.txt"]
}

Read an Excel File

Tool: fs_read
Arguments: {
  "path": "/data.xlsx",
  "sheet": "Sheet1",      # Optional, specify the worksheet
  "range": "A1:D100"      # Optional, specify the reading range
}

Create an Excel File

Tool: fs_write
Arguments: {
  "path": "/output.xlsx",
  "content": [
    ["Name", "Age", "City"],
    ["Alice", 30, "Beijing"],
    ["Bob", 25, "Shanghai"]
  ]
}

Edit an 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 to render complex charts:

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

📚 Documentation

💻 Web Development and Deployment

📁 File System Operations

📊 Excel Data Processing

🔍 Advanced Capabilities (Optional)

🔌 Integration with AI Platforms

🎯 Why Choose Our MCP Server?

We are a powerful All-in-One MCP Server. With just one configuration, we can provide your AI platform with complete Agent capabilities:

• ✅ 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: Full Excel/CSV processing capabilities.
• ✅ Image Generation: Mermaid flowcharts, data charts.
• ✅ Intelligent Search: Knowledge base retrieval, web page scraping (optional).

No need to integrate multiple MCP tools. One MCP Server meets all your needs!

🚀 Supported AI Platforms

We integrate perfectly with mainstream AI platforms, with simple configuration and out-of-the-box functionality:

Dify

1. Enter the Dify workflow configuration

   • Add an MCP Tool node.
   • Select the SSE transmission protocol.

2. Configure the MCP Server connection

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

3. Set the request headers (for 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 the FastGPT knowledge base/application configuration

   • Add an External Tool → MCP.
   • Select SSE as the transmission method.

2. Configure the connection information

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

3. Configure the user identifier (optional, for multi-tenant isolation)

   Custom Headers:
   X-User-ID: {{userId}}
   X-Chat-ID: {{chatId}}
   

4. Enable the tools: All tools are automatically available, no need to configure them individually!

Cherry Studio

1. Enter the Cherry Studio settings

   • Open the MCP Servers configuration.
   • Add a new MCP Server.

2. Configure the connection

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

3. Set the session identifier (for multi-tenant support)

   • Cherry Studio will automatically pass the user and session information.
   • Each session gets an independent workspace.

💡 Integration Advantages

🎁 Out-of-the-Box Capabilities

After configuration, your AI Agent immediately has:

• 📝 File Operations: Create, read, edit, and 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 = A complete Agent capability stack 🚀

🏗️ Architecture Design

┌─────────────────────────────────────────────────────────────┐
│          AI Platform (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 Conversion Layer           │    │
│  │         /todo.txt → /user_data/xxx/todo.txt         │    │
│  └─────────────────────────────────────────────────────┘    │
│                              │                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Path Security Verification              │    │
│  │         PathValidator + Path Traversal Protection     │    │
│  └─────────────────────────────────────────────────────┘    │
│                              │                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              File Operation Execution                │    │
│  │         FileOperations / AdvancedFileOperations      │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Physical File System                    │
│  user_data/                                                 │
│  ├── user1_chat1/                                           │
│  │   ├── todo.txt                                           │
│  │   └── docs/                                              │
│  ├── user1_chat2/                                           │
│  └── user2_chat1/                                           │
└─────────────────────────────────────────────────────────────┘

🔧 Technical Details

🔑 Authentication Configuration

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

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

# Edit the configuration and set your admin key
vim config.json

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

All Admin API requests must carry the Authorization header:

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

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 a Workspace

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

⚠️ Warning: This operation is irreversible! You must add the ?confirm=yes parameter to execute the deletion.

👤 User Workspace API

Provides a workspace directory tree query for users without the need for an admin token.

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 last modification time, and only the top 20 files/folders are retained. The rest are filtered directly to save bandwidth.

🧩 Excel Configuration

• Add an excel section to config.json/config.example.json to set the maximum file size, default number of rows to read, supported formats, and formula detection switch.
• Template: excel.templates_file points to excel_templates/templates.json by default. The template source files are placed in excel_templates/. Only title/desc are exposed externally. create_excel_from_template will automatically avoid duplicate names. When using it for the first time, copy templates_example.json to create templates.json and configure the template paths according to your actual situation.
• Environment variable override: MCP_EXCEL_MAX_ROWS, MCP_EXCEL_MAX_SIZE_MB.
• See docs/EXCEL_TOOLS.md for detailed parameters and examples.

⚙️ Startup Configuration

• Add an mcp section to config.json to 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: Add an admin_web section to config.json (enabled is false by default, password is 123456 by default). After enabling, access http://<host>:<port>/admin, enter the password to view the file tree under user_data and preview text/Markdown/CSV.

🔐 Security Best Practices

1. Production Environment Deployment

   • Use a reverse proxy (Nginx) to handle HTTPS.
   • Limit access IPs or use API key authentication.
   • Set reasonable request rate limits.

2. Data Isolation

   • Ensure that X-User-ID and X-Chat-ID are generated from trusted sources.
   • Regularly clean up expired session work directories.

3. Admin API Protection

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

⚙️ Environment Variables

📄 License

Apache License 2.0

🤝 Contribution

Welcome to submit Issues and Pull Requests!