🚀 MCP Workspace Server
🚀 只需一个 MCP，就能实现你的完整 Agent 能力！本项目是一个超越文件系统的 AI 开发环境，可让 AI 像 Claude Code 一样进行完整的 Web 开发、数据处理和代码执行。无需集成多个 MCP 工具，一个 MCP 服务器即可提供文件操作、代码执行、Web 部署、数据处理、图像生成等完整的 Agent 能力，是真正的一站式解决方案。
🚀 快速开始
Docker 部署（推荐）
git clone <repository-url>
cd mcp-filesystem
docker-compose up -d --build
> 如果无法使用docker镜像源，可以先执行 export DOCKER_BUILDKIT=0
git pull && docker-compose restart
docker-compose logs -f
docker-compose up -d --build
💡 使用建议
镜像包含运行环境，代码通过 volume 挂载，更新代码只需 git pull && docker-compose restart。
⚠️ 重要提示
本项目运行环境高度依赖 Docker 基础镜像，包含完整的 Python 3.12、Node.js 20 运行环境以及所有系统依赖（如 Tesseract OCR、图像处理库等）。强烈建议使用 Docker 方式部署，不推荐本地 Python 直接运行。如需本地开发，请确保已安装所有系统依赖。
快速配置参考
📖 详细集成说明：请查看上方的 🔌 与 AI 平台集成 章节，包含 Dify、FastGPT、Cherry Studio 的完整配置步骤。
快速连接信息：
- SSE 地址:
http://your-server:8000/sse
- 请求头（多租户隔离）:
X-User-ID: {{userId}} 或固定用户IDX-Chat-ID: {{chatId}} 或固定会话ID
Claude Desktop（STDIO 模式）：
编辑配置文件：
- 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"
]
}
}
}
✨ 主要特性
🔐 多租户会话隔离
每个用户/会话拥有独立的虚拟工作空间，完全隔离，互不干扰。
工作目录命名规则：
| X-User-ID |
X-Chat-ID |
工作目录 |
user123 |
chat456 |
user_data/user123_chat456/ |
user123 |
(空) |
user_data/user123/ |
| (空) |
chat456 |
user_data/chat456/ |
| (空) |
(空) |
使用默认全局模式 |
通过 HTTP 请求头传递身份标识：
X-User-ID: 用户唯一标识（可选）X-Chat-ID: 会话唯一标识（可选）
🛡️ 虚拟路径系统
LLM 视角完全虚拟化：AI 模型看到的是一个干净的虚拟文件系统，以 / 为根目录。
LLM 看到的路径 实际物理路径
─────────────────────────────────────────────────────────
/ → /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
优势：
- ✅ 不暴露服务器真实目录结构
- ✅ AI 平台无法获知物理路径信息
- ✅ 简化 AI 的文件操作指令
- ✅ 提升安全性和隐私保护
🔒 路径安全防护
内置多层安全机制，防止路径遍历攻击：
攻击尝试 结果
─────────────────────────────────────────────────
/../../../etc/passwd ❌ 被阻止
../../../etc/passwd ❌ 被阻止
/foo/../../../etc/passwd ❌ 被阻止
/foo/bar/../../.. ❌ 被阻止
安全机制：
- 路径解析：使用
Path.resolve() 解析所有 .. 和符号链接
- 边界检查：验证解析后的路径是否在允许范围内
- 双重保护：即使路径被解析，仍必须在
allowed_dirs 内
📡 SSE 传输协议
支持 Server-Sent Events (SSE) 传输，适配各类 AI 平台：
客户端 服务器
│ │
│──── GET /sse ──────────────────────▶│ 建立 SSE 连接
│◀─── SSE: endpoint=/messages?sid=xxx │ 返回消息端点
│ │
│──── POST /messages?session_id=xxx ─▶│ 发送工具调用
│◀─── SSE: message (响应) ───────────│ 接收结果
🌐 一键部署与泛域名支持
一键部署 Web 应用：
- AI 创建的前端项目可通过
preview_frontend 工具一键部署
- 自动生成可访问的 URL，支持 HTTPS
- 支持自定义入口文件和目录结构
泛域名部署（生产环境）：
{
"preview": {
"wildcard_domain": "*.proxy.your-domain.com",
"use_tls": true
}
}
配置后，每个会话自动获得独立子域名：
user123_chat456.proxy.your-domain.comuser789_chat012.proxy.your-domain.com
优势：
- ✅ 无需手动配置域名和端口
- ✅ 自动隔离，互不干扰
- ✅ 支持 HTTPS，生产就绪
- ✅ 单端口服务，简化部署
📦 安装指南
Docker 部署（推荐）
git clone <repository-url>
cd mcp-filesystem
docker-compose up -d --build
> 如果无法使用docker镜像源，可以先执行 export DOCKER_BUILDKIT=0
git pull && docker-compose restart
docker-compose logs -f
docker-compose up -d --build
💻 使用示例
🚀 Web 开发完整流程
基础用法
步骤 1：创建前端项目
Tool: fs_write
Arguments: {
"path": "/index.html",
"content": "<!DOCTYPE html>..."
}
步骤 2：一键部署
Tool: preview_frontend
Arguments: {
"entry_file": "index.html"
}
返回结果：
{
"success": true,
"url": "https://user123_chat456.proxy.your-domain.com/index.html",
"subdomain": "user123_chat456"
}
步骤 3：访问部署的应用
- 自动获得独立子域名
- 支持 HTTPS（如配置）
- 无需手动配置端口和域名
高级用法
代码执行与调试
Tool: fs_read
Arguments: {
"path": "/file.txt",
"line_range": "100:150"
}
Tool: fs_read
Arguments: {
"path": ["/file1.txt", "/file2.json", "/data.xlsx"]
}
Tool: fs_search
Arguments: {
"search_type": "content",
"pattern": "function\\s+\\w+\\(",
"context_lines": 2
}
Tool: fs_replace
Arguments: {
"path": "/config.py",
"diff": "------- SEARCH\nDEBUG = True\n========\nDEBUG = False\n+++++++ REPLACE"
}
Tool: exec
Arguments: {
"code": "print('Hello, World!')"
}
Tool: exec
Arguments: {
"file": "/script.py",
"args": ["--verbose", "input.txt"]
}
Tool: fs_read
Arguments: {
"path": "/data.xlsx",
"sheet": "Sheet1",
"range": "A1:D100"
}
Tool: fs_write
Arguments: {
"path": "/output.xlsx",
"content": [
["Name", "Age", "City"],
["Alice", 30, "Beijing"],
["Bob", 25, "Shanghai"]
]
}
Tool: excel_edit
Arguments: {
"path": "/data.xlsx",
"edit_type": "cells",
"sheet": "Sheet1",
"updates": [
{"cell": "A1", "value": "Updated Value"}
]
}
Tool: generate_image
Arguments: {
"mermaid_code": "flowchart TD\nA[开始] --> B[处理] --> C[结束]"
}
Tool: generate_image
Arguments: {
"html_code": "<html><body><h1>数据可视化</h1>...</body></html>"
}
📚 详细文档
与 AI 平台集成
🎯 为什么选择我们作为你的 MCP Server？
我们是强大的 All-in-One MCP Server，只需一次配置，即可为你的 AI 平台提供完整的 Agent 能力：
- ✅ 文件操作：读写、搜索、编辑文件
- ✅ 代码执行：Python/Node.js 沙盒环境
- ✅ Web 部署：一键部署前端应用，支持泛域名
- ✅ 数据处理：Excel/CSV 完整处理能力
- ✅ 图像生成：Mermaid 流程图、数据图表
- ✅ 智能搜索：知识库检索、网页抓取（可选）
无需集成多个 MCP 工具，一个 MCP Server 即可满足所有需求！
🚀 支持的 AI 平台
我们与主流 AI 平台完美集成，配置简单，开箱即用：
Dify
- 进入 Dify 工作流配置
- 添加 MCP Tool 节点
- 选择 SSE 传输协议
- 配置 MCP Server 连接
SSE 地址: http://your-server:8000/sse
- 设置请求头（多租户隔离）
X-User-ID: {{user_id}}
X-Chat-ID: {{conversation_id}}
- 完成！ 现在你的 Dify Agent 拥有完整的文件操作、代码执行、Web 部署等能力。
FastGPT
- 进入 FastGPT 知识库/应用配置
- 配置连接信息
MCP Server URL: http://your-server:8000/sse
- 配置用户标识（可选，用于多租户隔离）
自定义 Header:
X-User-ID: {{userId}}
X-Chat-ID: {{chatId}}
- 启用工具：所有工具自动可用，无需逐个配置！
Cherry Studio
- 进入 Cherry Studio 设置
- 打开 MCP Servers 配置
- 添加新的 MCP Server
- 配置连接
{
"name": "MCP Workspace Server",
"transport": "sse",
"url": "http://your-server:8000/sse"
}
- 设置会话标识（多租户支持）
- Cherry Studio 会自动传递用户和会话信息
- 每个会话获得独立的工作空间
💡 集成优势
| 传统方案 |
使用我们的 All-in-One MCP |
| 需要 5+ 个 MCP 工具 |
只需 1 个 MCP |
| 配置复杂，需要逐个集成 |
开箱即用，一键配置 |
| 功能分散，难以统一管理 |
功能集中，统一管理 |
| 安全策略不统一 |
统一安全策略 |
| 维护成本高 |
维护简单 |
🎁 开箱即用的能力
配置完成后，你的 AI Agent 立即拥有：
- 📝 文件操作：创建、读取、编辑、搜索文件
- 💻 代码执行：运行 Python/Node.js 脚本，实时调试
- 🌐 Web 开发：创建前端应用并一键部署到生产环境
- 📊 数据处理：读取、编辑 Excel，生成报告
- 🎨 图像生成：创建流程图、数据可视化图表
- 🔍 智能搜索：文件内容搜索、知识库检索（如启用）
一个 MCP Server = 完整的 Agent 能力栈 🚀
架构设计
┌─────────────────────────────────────────────────────────────┐
│ 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/ │
└─────────────────────────────────────────────────────────────┘
管理员 API
🔑 认证配置
Admin API 需要 Bearer Token 认证。首先配置 config.json：
cp config.example.json config.json
vim config.json
{
"admin_token": "your-secret-admin-token-here"
}
所有 Admin API 请求必须携带 Authorization 头：
curl -H "Authorization: Bearer your-secret-admin-token-here" \
http://localhost:8000/admin/stats
⚠️ 安全提示：config.json 已添加到 .gitignore，请勿将其提交到版本库。
获取服务器统计信息
GET /admin/stats
Authorization: Bearer <admin_token>
响应示例：
{
"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
}
列出所有工作空间
GET /admin/workspaces
GET /admin/workspaces?user_id=user123
Authorization: Bearer <admin_token>
获取工作空间详情
GET /admin/workspace/{workspace_id}
GET /admin/workspace/{workspace_id}/tree?max_depth=5
Authorization: Bearer <admin_token>
删除工作空间
DELETE /admin/workspace/{workspace_id}?confirm=yes
Authorization: Bearer <admin_token>
⚠️ 警告：此操作不可逆！必须添加 ?confirm=yes 参数才能执行删除。
用户工作空间 API
为用户提供无需管理员 Token 的工作空间目录树查询。
GET /api/workspace/tree?user_id={user_id}&chat_id={chat_id}&max_depth=5
- 不需要
Authorization 头
- 仅返回对应
user_id + chat_id 组合的工作空间
- 每个目录层级按最近修改时间排序，仅保留前 20 个文件/文件夹，其余直接过滤以节省带宽
Excel 配置
config.json/config.example.json 新增 excel 段落，用于设置最大文件大小、默认读取行数、支持格式与公式检测开关。- 模板：
excel.templates_file 默认指向 excel_templates/templates.json，模板源文件放在 excel_templates/，对外只暴露 title/desc，create_excel_from_template 会自动避开重名。首次使用时，请从 templates_example.json 复制创建 templates.json，并根据实际情况配置模板路径。
- 环境变量覆盖：
MCP_EXCEL_MAX_ROWS、MCP_EXCEL_MAX_SIZE_MB。
- 详细参数与示例见
docs/EXCEL_TOOLS.md。
启动配置
config.json 中新增 mcp 段落，可配置 transport（默认 sse）、host（默认 0.0.0.0）、port（默认 18089）。- CLI 参数
--transport/--host/--port 优先级高于配置文件。
- Web 管理界面：
config.json 新增 admin_web 段落（enabled 默认 false，password 默认 123456）。开启后访问 http://<host>:<port>/admin，输入密码可查看 user_data 下文件树并预览文本/Markdown/CSV。
🔧 技术细节
为什么选择我们？
🎯 一个 MCP，完整 Agent 能力
传统方案：需要集成多个 MCP 工具才能实现完整功能
- ❌ 文件操作 → 需要一个 MCP
- ❌ 代码执行 → 需要另一个 MCP
- ❌ Web 部署 → 需要第三个 MCP
- ❌ 数据处理 → 需要第四个 MCP
- ❌ 图像生成 → 需要第五个 MCP
- 结果：配置复杂、维护困难、功能分散
我们的方案：只需一个 MCP，所有能力开箱即用
- ✅ 文件操作 + 代码执行 + Web 部署 + 数据处理 + 图像生成
- ✅ 统一配置：一次配置，全部启用
- ✅ 统一管理：一个服务，集中管理
- ✅ 统一安全：一套安全策略，全面保护
我们提供的是完整的 AI 开发工作空间，能力远超传统文件系统服务器：
- 🚀 Web 开发能力：AI 可以创建完整的 Web 应用（HTML/CSS/JS），并一键部署到生产环境
- 🌐 泛域名部署：支持
*.your-domain.com 泛域名，每个会话自动获得独立子域名访问
- 💻 代码执行：内置 Python 3.12 和 Node.js 20 沙盒环境，支持代码实时执行和调试
- 📊 数据处理：完整的 Excel/CSV 处理能力，支持模板、公式、格式化
- 🎨 图像生成：支持 Mermaid 流程图、数据图表、HTML 渲染等多种图像生成方式
- 🔍 智能搜索：文件内容搜索、知识库检索、网页抓取等高级能力
- 🔐 企业级安全：多租户隔离、路径安全防护、资源限制、沙盒执行
🎁 All-in-One 优势
| 传统方案 |
我们的方案 |
| 需要 5+ 个 MCP 工具 |
只需 1 个 MCP |
| 配置复杂，需要逐个集成 |
开箱即用，一键配置 |
| 功能分散，难以统一管理 |
功能集中，统一管理 |
| 安全策略不统一 |
统一安全策略 |
| 维护成本高 |
维护简单 |
一句话总结：一个 MCP 服务器 = 完整的 Agent 能力栈 🚀
💡 典型使用场景
场景 1：AI 驱动的 Web 开发
AI 创建完整的前端应用 → 一键部署 → 获得独立域名访问
例如：https://user123_chat456.your-domain.com
场景 2：数据分析与可视化
读取 Excel → 数据处理 → 生成图表 → 创建报告 → 部署展示页面
场景 3：代码开发与测试
编写 Python 脚本 → 执行测试 → 修复 Bug → 部署 API 服务
📄 许可证
Apache License 2.0
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
