1. 为什么要在本地跑 ONLYOFFICE 协作空间 MCP 服务器ONLYOFFICE 协作空间 MCP 服务器简单说就是把「文档协作空间」包装成一套 AI 能直接调用的工具集。它基于模型上下文协议MCP让 Claude Desktop、Cursor、Cline 这类支持 MCP 的客户端通过标准化的工具调用去操作协作空间里的文件、文件夹、房间和成员。适合谁主要是开发者、DevOps以及正在把 AI 塞进文档工作流的团队——如果你平时要在协作空间里批量上传文档、建房间、归档项目文件夹又不想每次都手点网页这套东西就是给你准备的。它本质上是一个 Node 进程通过npx拉起用环境变量告诉它「协作空间实例在哪、用什么 Key 认证、开哪些工具集」。客户端比如 Claude Desktop在settings.json里声明这个 server启动后就能看到create_folder、upload_file、create_room、archive_room等 20 多个工具。AI 模型不再只是聊天而是能真的去建文件夹、传文件、设权限。但这里有个现实问题MCP 客户端本身要连大模型而模型调用需要 Key。如果你同时用多个 AI 工具Claude Code、Cursor、Cline每个都单独配 Key、单独管额度很快就会乱。所以这篇我会用 TaoToken 做统一 Key 层把模型调用收敛到一个入口再让 ONLYOFFICE MCP 服务器专注干文档协作的活。整条链路是MCP 客户端 → TaoToken模型→ ONLYOFFICE MCP 服务器工具→ 协作空间实例。下面从零开始把本地 MCP 服务搭起来配置骨架、启动、连通性验证、排错一步步走完。2. 前置准备TaoToken 统一 Key 与协作空间凭据在写配置文件之前先把两边的凭据准备好不然后面配置里全是占位符跑起来必报错。第一块是 TaoToken 的 API Key。TaoToken 在这里的角色是「模型调用的统一入口」你的 MCP 客户端Claude Desktop、Cline 等通过它去访问模型。先去控制台创建 Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_onlyoffice_consoleAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_onlyoffice_apikeys创建完把 Key 复制出来形如sk-xxxx先存到本地环境变量或密码管理器里别直接写进会提交到 Git 的文件。第二块是 ONLYOFFICE 协作空间的凭据。你需要三样东西变量含义从哪拿DOCSPACE_BASE_URL协作空间实例地址你的部署域名如https://docspace.example.comDOCSPACE_API_KEYAPI 密钥协作空间后台的开发者/集成设置里生成DOCSPACE_AUTH_TOKEN认证令牌部分场景需要用于免重复手动认证注意DOCSPACE_API_KEY和DOCSPACE_AUTH_TOKEN不是一回事。前者标识「哪个集成在调用」后者是「以谁的身份调用」。如果工具调用返回 401/403优先检查这两个是否配对正确。TaoToken 的接入文档在这里配置模型侧参数时可以对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_onlyoffice_doc环境要求Node.js 18建议 20 LTS因为服务器通过npx拉起如果要从源码构建还需要 pnpm。先确认版本node -v npm -v npx -v三条都能输出版本号说明基础环境 OK。如果npx报找不到命令说明 npm 没装全重装 Node 即可。3. 可复制配置settings.json 与 config.toml 骨架MCP 客户端的配置分两种常见格式JSONClaude Desktop、Cline 等和 TOML部分工具如 Codex 风格客户端。我两个都给你按自己用的客户端选。3.1 Claude Desktop / Cline 的 settings.jsonClaude Desktop 的配置文件位置macOS 在~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 在%APPDATA%\Claude\claude_desktop_config.json。Cline 则在 VS Code 设置里的 MCP Servers 配置区。骨架如下{ mcpServers: { onlyoffice-docspace: { command: npx, args: [--yes, onlyoffice/docspace-mcp], env: { DOCSPACE_BASE_URL: https://your-instance.onlyoffice.com, DOCSPACE_API_KEY: your-docspace-api-key, DOCSPACE_AUTH_TOKEN: your-docspace-auth-token, DOCSPACE_TRANSPORT: stdio, DOCSPACE_TOOLSETS: files,folders,rooms,members } } } }几个关键点解释一下。commandargs是启动方式npx --yes表示自动确认安装包不用手动npm install。env里前三个是协作空间凭据DOCSPACE_TRANSPORT用stdio表示走标准输入输出这是本地 MCP 最常用的传输方式。DOCSPACE_TOOLSETS限定只加载文件、文件夹、房间、成员四组工具避免一次性暴露全部 20 多个工具导致模型选择困难。如果你还想在同一份配置里接 TaoToken 的模型可以在客户端侧单独配模型 provider把 base URL 指向https://taotoken.net/apiKey 用前面创建的。模型配置和 MCP server 配置是两层别混在一个env里。3.2 config.toml 骨架部分客户端用 TOML。等价配置如下[mcp_servers.onlyoffice-docspace] command npx args [--yes, onlyoffice/docspace-mcp] [mcp_servers.onlyoffice-docspace.env] DOCSPACE_BASE_URL https://your-instance.onlyoffice.com DOCSPACE_API_KEY your-docspace-api-key DOCSPACE_AUTH_TOKEN your-docspace-auth-token DOCSPACE_TRANSPORT stdio DOCSPACE_TOOLSETS files,folders,rooms,membersTOML 里字符串必须用双引号数组用方括号别写成 JSON 的花括号这是最常见的格式错误。3.3 工具集与工具级开关除了DOCSPACE_TOOLSETS还有两个更细的开关DOCSPACE_ENABLED_TOOLS白名单只开指定工具如create_folder,upload_fileDOCSPACE_DISABLED_TOOLS黑名单排除危险操作如archive_room生产环境建议用白名单只放你确认安全的工具。比如只让 AI 建文件夹和传文件不给它归档和改权限的能力DOCSPACE_ENABLED_TOOLS: create_folder,upload_file,get_file_info另外还有DOCSPACE_DYNAMIC开启后把所有工具分组到「元工具」里模型按需动态加载而不是一次性全塞进上下文。工具多的时候这个能明显降低上下文占用。4. 启动服务与连通性验证配置写完先别急着开客户端用命令行单独把 MCP 服务器拉起来确认它能正常启动、能连上协作空间。4.1 手动启动测试在终端里直接跑把环境变量带上export DOCSPACE_BASE_URLhttps://your-instance.onlyoffice.com export DOCSPACE_API_KEYyour-docspace-api-key export DOCSPACE_AUTH_TOKENyour-docspace-auth-token export DOCSPACE_TRANSPORTstdio npx --yes onlyoffice/docspace-mcp如果启动成功进程会挂起等待 stdio 输入终端没有报错就是好信号。如果立刻退出并打印错误看下一节的排错。4.2 用 MCP Inspector 验证工具列表MCP 官方有个 Inspector 工具能可视化看到服务器暴露了哪些工具。启动方式npx --yes modelcontextprotocol/inspector npx --yes onlyoffice/docspace-mcp它会打开一个本地网页左侧列出所有可用工具。你应该能看到create_folder、get_file_info、upload_file、create_room、set_room_security、archive_room等。点进某个工具填入参数可以直接发起调用。4.3 实际调用一次 create_folder在 Inspector 里选create_folder参数大致是父目录 ID 和文件夹名。调用成功后回到协作空间网页端刷新应该能看到新建的文件夹。这一步跑通说明「MCP 服务器 → 协作空间」这条链路是通的。再试一次get_file_info传一个已存在文件的 ID返回元数据名称、大小、创建时间。这个工具是只读的适合用来做连通性冒烟测试不会产生副作用。4.4 在客户端里确认工具可见重启 Claude Desktop 或 Cline在对话里问一句「你现在能用哪些 ONLYOFFICE 工具」。如果配置正确模型会列出已加载的工具集。此时让它执行「在协作空间根目录建一个叫 demo-2025 的文件夹」观察它是否调用create_folder并返回成功。如果模型说「我没有这个工具」八成是客户端没读到配置文件或者 JSON 格式有误多逗号、少引号。用python -m json.tool your_config.json校验一下 JSON 合法性。5. 本篇常见错误排查这一节是我实际配置时踩过的坑按出现频率排序。错误一npx拉包超时或 404。通常是网络或 npm 源问题。先确认包名拼写onlyoffice/docspace-mcp注意 scope 是onlyoffice。可以手动npm view onlyoffice/docspace-mcp version看能否查到版本。错误二启动后立刻退出日志显示缺少环境变量。MCP 服务器对DOCSPACE_BASE_URL和DOCSPACE_API_KEY是强依赖缺一个就起不来。检查env块是否写全键名大小写是否一致——环境变量是大小写敏感的。错误三工具调用返回 401/403。认证问题。先确认DOCSPACE_API_KEY有效且未过期如果协作空间要求令牌补上DOCSPACE_AUTH_TOKEN。还有一种情况是 Key 的权限范围不够比如只给了读权限却调用upload_file这时要去协作空间后台调整集成的权限。错误四工具列表为空。检查DOCSPACE_TOOLSETS是否写成了不存在的名字。合法的工具集名是files、folders、rooms、members这类写错一个字母整组都不加载。可以先把这个变量删掉让默认全部加载确认能出工具后再逐步收窄。错误五客户端里工具可见但调用报「连接失败」。多半是DOCSPACE_BASE_URL带了多余路径或少了协议头。正确形式是https://域名不要带/api后缀也不要漏https://。错误六中文文件名乱码。确保客户端和服务器都用 UTF-8。JSON 配置文件本身要存成 UTF-8 无 BOM 格式Windows 记事本默认可能带 BOM用 VS Code 另存为 UTF-8 即可。错误七DOCSPACE_DYNAMIC开启后模型找不到具体工具。元工具模式下模型需要先「发现」再「调用」对模型能力有要求。如果用的模型不支持这种两段式调用关掉DOCSPACE_DYNAMIC回到直接暴露工具的模式。提示这个 MCP 服务器目前处于预览状态功能可用但可能有破坏性变更。生产环境用之前先在测试实例上跑一遍完整流程锁定版本号别用latest自动升级。6. 把模型调用也收敛到 TaoToken工具链路通了之后剩下就是模型侧。如果你只用 Claude Desktop 自带的模型可以跳过这节。但如果你同时用 Claude Code、Cursor、Cline 做编码和 Agent 任务建议把模型调用统一走 TaoToken一个 Key 管所有客户端。模型对话入口在这里可以先在网页上验证 Key 是否可用https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_onlyoffice_chat长期做编码和 Agent 的看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_onlyoffice_codingplan如果你用 Claude Code 这类工具接入文档里有对应的 base URL 和 Key 配置说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_onlyoffice_claudecode配置思路很简单客户端里模型 provider 的 base URL 填https://taotoken.net/apiAPI Key 填你在控制台创建的那个。MCP server 的配置保持不变两者互不干扰。这样你的架构就是「模型走 TaoToken工具走 ONLYOFFICE MCP」职责清晰换模型或换工具都不用动另一边。最后给一个实用技巧把协作空间的凭据和 TaoToken 的 Key 都放进系统环境变量或.env文件配置文件里用占位符引用。这样配置文件可以安全地提交到团队仓库每个人本地填自己的凭据就行。我试过把 Key 硬编码进 JSON 再提交结果轮换 Key 时改了七八个文件血的教训。