Which integrations are available for this server?

Recommended deployment method using [Docker](/mcp/servers/integrations/docker) containers with pre-configured Python 3.12 and Node.js 20 runtime environments Supports reading and rendering [Markdown](/mcp/servers/integrations/markdown) files through the file operations and web crawling tools Enables generation of flowcharts and diagrams from [Mermaid](/mcp/servers/integrations/mermaid) code syntax through the image generation tools Recommended as reverse proxy for handling HTTPS in production deployments with wildcard domain support Provides sandboxed [Node.js](/mcp/servers/integrations/node-dot-js) 20 code execution environment for running JavaScript applications and web development Provides sandboxed [Python](/mcp/servers/integrations/python) 3.12 code execution environment for running scripts and performing data processing tasks

MCP Workspace Server

English | 中文

License

🚀 只需一个 MCP，就能实现你的完整 Agent 能力！

超越文件系统的 AI 开发环境 - 让 AI 像 Claude Code 一样进行完整的 Web 开发、数据处理和代码执行

💡 核心价值：无需集成多个 MCP 工具，一个 MCP 服务器即可提供文件操作、代码执行、Web 部署、数据处理、图像生成等完整的 Agent 能力。开箱即用，一站式解决方案。

一个功能强大的 MCP (Model Context Protocol) 服务器，不仅提供安全的文件系统操作，更是一个完整的 AI 开发工作空间。支持代码执行、Web 应用一键部署、泛域名访问、Excel 处理、图像生成等企业级能力。

✨ 为什么选择我们？

🎯 一个 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 服务

✨ 核心特性

🔐 多租户会话隔离

每个用户/会话拥有独立的虚拟工作空间，完全隔离，互不干扰。

工作目录命名规则：

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.com
user789_chat012.proxy.your-domain.com

优势：

✅ 无需手动配置域名和端口
✅ 自动隔离，互不干扰
✅ 支持 HTTPS，生产就绪
✅ 单端口服务，简化部署

📦 完整功能列表

💻 Web 开发与部署

工具	功能	亮点
`fs_write`	创建 Web 文件（HTML/CSS/JS）	自动识别格式，支持完整前端项目
`preview_frontend`	一键部署静态前端	支持泛域名，自动生成独立子域名
`exec`	执行 Python/Node.js 代码	沙盒环境，支持实时调试
`generate_image`	生成图表和流程图	Mermaid、数据可视化、HTML 渲染

📁 文件系统操作

工具	功能
`fs_read`	读取文件（支持批量、Excel、行范围）
`fs_write`	创建/覆盖文件（自动识别格式）
`fs_ops`	文件系统操作（list/mkdir/move/info/delete）
`fs_replace`	基于 SEARCH/REPLACE 精确编辑文件
`fs_search`	搜索文件（glob=按文件名，content=按内容正则）

📊 Excel 数据处理

工具	功能
`fs_read`	读取 Excel 文件（支持 sheet、range 参数）
`fs_write`	创建/覆盖 Excel 文件（自动识别格式）
`excel_edit`	编辑 Excel（批量更新单元格、格式化）
`list_excel_templates`	列出可用 Excel 模板
`create_excel_from_template`	从模板创建 Excel 文件

🔍 高级能力（可选）

工具	功能	配置项
`kb_search`	企业知识库 glob 搜索	`kb.enabled=true`
`kb_read`	读取知识库文件（返回 Markdown）	`kb.enabled=true`
`crawl_url`	抓取网页并返回 Markdown	`web_crawl.enabled=true`
`web_search`	联网搜索	`web_search.enabled=true`

🔌 与 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
- 传输方式选择 SSE
配置连接信息
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 Server
每个工具需要单独连接和认证	一次配置，全部启用
工具之间功能分散，难以统一管理	功能集中，统一管理
不同工具的安全策略不一致	统一安全策略，全面保护
维护多个服务的成本高	维护简单，一个服务搞定

🎁 开箱即用的能力

配置完成后，你的 AI Agent 立即拥有：

📝 文件操作：创建、读取、编辑、搜索文件
💻 代码执行：运行 Python/Node.js 脚本，实时调试
🌐 Web 开发：创建前端应用并一键部署到生产环境
📊 数据处理：读取、编辑 Excel，生成报告
🎨 图像生成：创建流程图、数据可视化图表
🔍 智能搜索：文件内容搜索、知识库检索（如启用）

一个 MCP Server = 完整的 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}} 或固定用户ID
- X-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" ] } } }

🏗️ 架构设计

┌─────────────────────────────────────────────────────────────┐ │ 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

提供 HTTP 接口用于监控、调试和运维。

🔑 认证配置

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。

📖 使用示例

🚀 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" # 读取第100-150行 }

批量读取文件

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

搜索文件

Tool: fs_search Arguments: { "search_type": "content", # glob=按文件名, content=按内容 "pattern": "function\\s+\\w+\\(", "context_lines": 2 # 返回匹配行前后2行上下文 }

精确编辑文件

Tool: fs_replace Arguments: { "path": "/config.py", "diff": "------- SEARCH\nDEBUG = True\n========\nDEBUG = False\n+++++++ REPLACE" }

执行 Python 代码

Tool: exec Arguments: { "code": "print('Hello, World!')" }

执行 Python 文件

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

读取 Excel 文件

Tool: fs_read Arguments: { "path": "/data.xlsx", "sheet": "Sheet1", # 可选，指定工作表 "range": "A1:D100" # 可选，指定读取范围 }

创建 Excel 文件

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

编辑 Excel 文件

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[结束]" }

或使用 HTML 渲染复杂图表：

Tool: generate_image Arguments: { "html_code": "<html><body><h1>数据可视化</h1>...</body></html>" }

🔐 安全最佳实践

生产环境部署
- 使用反向代理（Nginx）处理 HTTPS
- 限制访问 IP 或使用 API 密钥认证
- 设置合理的请求频率限制
数据隔离
- 确保 X-User-ID 和 X-Chat-ID 由可信来源生成
- 定期清理过期的会话工作目录
Admin API 保护
location /admin/ { allow 10.0.0.0/8; deny all; proxy_pass http://localhost:8000; }

⚙️ 环境变量

变量名	说明	默认值
`MCP_WORKSPACES_DIR`	用户工作空间根目录	`项目目录/user_data`
`MCP_ALLOWED_DIRS`	允许访问的目录列表（全局模式）	当前工作目录
`FASTMCP_PORT`	服务器端口	`8000`

📄 许可证

Apache License 2.0

🤝 贡献

欢迎提交 Issue 和 Pull Request！