腾讯文档扩展 MCP

让 Codex、Claude、WorkBuddy、Cursor 等支持本地 stdio MCP 的 AI 客户端，使用腾讯官方 MCP 尚未提供的功能。本项目不再代理或重复腾讯官方 MCP。

• 收集表题目读取、编辑、发布和公开回读验证。

• 收藏、共享、回收站、恢复、快捷方式、置顶等官方 MCP 未打包的文件管理能力。

• 21 项官方 MCP 未提供或只提供较窄版本的正式 Open API 能力，另有 4 个本机授权管理工具。

• 当前共 38 个工具；不包含官方 MCP 已有的 224 个工具。

这是社区项目，不是腾讯官方产品。项目同时包含正式 Open API 和网页内部接口；后者可能随腾讯改版失效。已安装腾讯官方 MCP 的用户可以与本项目并行使用。

支持的 AI 客户端

项目使用标准本地 stdio MCP，不绑定某一个 AI 产品。已经提供配置格式的客户端包括：

• Codex 桌面版和 Codex CLI

• Claude Desktop 和 Claude Code

• WorkBuddy

• Cursor、VS Code 等能够配置本地 stdio MCP 的客户端

AI 产品本身如果不支持 MCP，无法直接加载本项目。Claude.ai、ChatGPT 网页版等只接受远程 Connector 的场景，需要另行部署 Streamable HTTP 服务；当前仓库默认是更适合个人账号和本机凭据的 stdio 版本。

Related MCP server: Google Forms MCP

验证情况

安装

需要 Python 3.10 或更高版本，并先在浏览器中登录 腾讯文档。

macOS / Linux

git clone https://github.com/kakadamowanglaile/tencent-docs-form-mcp.git
cd tencent-docs-form-mcp
chmod +x install.sh run-mcp.sh
./install.sh

Windows

在 PowerShell 中执行：

git clone https://github.com/kakadamowanglaile/tencent-docs-form-mcp.git
cd tencent-docs-form-mcp
powershell -ExecutionPolicy Bypass -File .\install-windows.ps1

安装完成后运行一次登录助手：

.\.venv\Scripts\python.exe .\browser_login.py

它会自动寻找 Chrome、Edge、Brave、Vivaldi 或 Chromium，打开腾讯文档登录页。你登录成功后窗口会立即自动关闭，并由 Windows 使用当前系统账号加密保存登录状态。没有 Chrome 时会自动使用 Edge，不需要你预先新建表单。

正式 Open API 一键授权

正式 Open API OAuth2 与腾讯官方 MCP 的授权无关。每位用户使用自己在腾讯文档开放平台创建并审核的应用，不共享仓库作者的账号或密钥。

首次使用：

1. 在开放平台应用中开通需要的权限并通过审核。

   • 读取文档分享权限：scope.drive.file.permission.readonly 或 scope.drive.file.permission

   • 读取文件夹操作权限：还可使用 scope.drive.file.metadata

2. 把下列 HTTPS 回调地址加入应用白名单：

https://kakadamowanglaile.github.io/tencent-docs-form-mcp/

3. 双击项目根目录的 授权腾讯文档.command（macOS）或 授权腾讯文档.bat（Windows）。也可以在项目目录运行：

macOS / Linux：

.venv/bin/python openapi_setup.py

Windows PowerShell：

.\.venv\Scripts\python.exe .\openapi_setup.py

程序会打开仅限本机访问的设置窗口。第一次粘贴自己的 Client ID 和 Client Secret，点击“保存并授权”；以后只显示一个“授权腾讯文档”按钮。Client Secret 保存到当前操作系统的密钥库。用户确认后，一次性授权码经静态 HTTPS 页面返回本机 127.0.0.1:49680-49689 的专用端口，本机换取并保存 Token。中转页不接收 Client Secret、Access Token 或 Refresh Token。

已经把 MCP 加到 AI 客户端时，也可以直接让 AI 调用 tencent_docs_openapi_setup。它会在用户电脑上打开同一个本机设置窗口，配置值不会作为 MCP 工具参数传给 AI。

正常的 Token 过期会自动使用 Refresh Token 更新；尚未授权或需要重新授权时，AI 可直接调用 tencent_docs_openapi_login。高级用户仍可使用 examples/openapi.env.example 的环境变量方式。

检查登录态

把链接换成你自己创建的腾讯文档原生收集表。

macOS：

.venv/bin/python auth_check.py \
  --form-url "https://docs.qq.com/form/page/你的表单TOKEN" \
  --browser chrome

Windows 登录后不必提供已有表单；可以让 MCP 直接新建。若要检查某个已有表单，可运行：

$env:TENCENT_DOCS_USE_SAVED_LOGIN = "1"
.\.venv\Scripts\python.exe .\auth_check.py `
  --form-url "https://docs.qq.com/form/page/你的表单TOKEN" `
  --saved-login

该命令只显示登录和编辑权限状态，不输出 Cookie。

添加到任意 MCP 客户端

核心配置只有两个值：Python 解释器路径和 gateway.py 的绝对路径。JSON 客户端可以使用下面的配置；WorkBuddy、Claude Desktop 以及采用 mcpServers 格式的客户端均可参考。

macOS 示例：

{
  "mcpServers": {
    "tencent-docs-extensions": {
      "command": "/你的路径/tencent-docs-form-mcp/.venv/bin/python",
      "args": [
        "/你的路径/tencent-docs-form-mcp/gateway.py"
      ],
      "env": {
        "TENCENT_DOCS_USE_BROWSER_COOKIES": "1",
        "TENCENT_DOCS_BROWSER": "chrome"
      }
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "tencent-docs-extensions": {
      "command": "C:\\你的路径\\tencent-docs-form-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\你的路径\\tencent-docs-form-mcp\\gateway.py"
      ],
      "env": {
        "TENCENT_DOCS_USE_SAVED_LOGIN": "1"
      }
    }
  }
}

可复制的 JSON 和 TOML 模板位于 examples 目录。不要整份覆盖客户端现有配置，只增加 tencent-docs-extensions 这一项。推荐用 openapi_setup.py 把凭据保存到系统密钥库；环境变量模板仅供高级用户和 CI 使用。

Codex

把对应示例中的内容加入 ~/.codex/config.toml：

• macOS/Linux：mcp-config.codex.macos.example.toml

• Windows：mcp-config.codex.windows.example.toml

Claude Code

Claude Code 可以把同样的 stdio 配置加入用户级 MCP：

claude mcp add-json --scope user tencent-docs-extensions '{"type":"stdio","command":"/ABSOLUTE/PATH/tencent-docs-form-mcp/.venv/bin/python","args":["/ABSOLUTE/PATH/tencent-docs-form-mcp/gateway.py"],"env":{"TENCENT_DOCS_USE_BROWSER_COOKIES":"1","TENCENT_DOCS_BROWSER":"chrome"}}'

Windows PowerShell 可以直接使用 mcp-config.windows.example.json 中的服务器对象，通过 claude mcp add-json 添加。Claude Desktop 可在本地 MCP 或扩展开发配置中使用同一对象。

WorkBuddy 和其他 JSON 客户端

使用 mcp-config.macos.example.json 或 mcp-config.windows.example.json。保存并重启客户端后，可以这样说：

gateway.py 仅为兼容旧配置的启动入口，不会连接或代理腾讯官方 MCP。

检查这个腾讯文档收集表，然后把题目改成姓名、手机号、报名项目三个问题，确认后发布。表单链接是……

WorkBuddy 市场连接器

仓库的 workbuddy-connector 是 WorkBuddy 5.0.0 及以上版本可上传的 CLI + Skill 连接器源目录。WorkBuddy 会管理 Python 运行时，用户不需要手工安装 Python。

生成审核 ZIP：

.venv/bin/python scripts/build_workbuddy_connector.py

默认产物是 dist/tencent-docs-extensions-workbuddy-0.8.0.zip。ZIP 内的 connector-meta.json、cli.json、icon.svg 和 skills/ 直接位于根目录，可在 WorkBuddy 开放平台的“发布管理 → 连接器”中上传。

该连接器使用本机浏览器中已登录的腾讯文档会话。Cookie 不写入 ZIP、GitHub 或 AI 对话。点击断开后，连接器会停止使用该登录态，但不会代替用户退出浏览器里的腾讯文档账号。

MCP 工具

本项目只暴露腾讯官方 MCP 未提供的扩展工具。普通文档、表格、幻灯片、OCR、最近文件、文件夹列表和空白收集表创建等能力，请直接安装腾讯官方 MCP。

本项目的扩展工具：

• tencent_docs_login：Windows 上自动弹出可用浏览器，登录成功后立即关窗并加密保存登录状态。

• tencent_docs_inspect_form：读取题目、发布状态和当前账号权限，不修改内容。

• tencent_docs_replace_form_questions：完整替换题目但不发布。

• tencent_docs_publish_form：发布现有草稿，并检查公开版本。

• tencent_docs_build_and_publish_form：替换题目、设置匿名选项、发布并检查公开版本。

• tencent_docs_create_and_publish_form：新建收集表、写入题目、发布并检查公开版本，不需要预先提供表单链接。

• tencent_docs_list_files：读取收藏、与我共享或回收站列表。

• tencent_docs_set_starred：收藏或取消收藏。

• tencent_docs_restore_file：从回收站恢复文件。

• tencent_docs_add_shortcut：在指定文件夹创建文件快捷方式。

• tencent_docs_set_pinned：置顶或取消置顶。

• tencent_docs_permanently_delete_trash_item：永久删除单个回收站项目，必须精确提供确认词。

• tencent_docs_clear_trash：永久清空回收站，必须精确提供确认词。

正式 Open API 工具：

• tencent_docs_openapi_status：检查配置，也可实际校验 Access Token；不返回任何凭据值。

• tencent_docs_openapi_setup：打开本机设置窗口；首次填写应用信息，以后只需点击授权。

• tencent_docs_openapi_login：打开腾讯官方授权页，自动接收回调、换 Token 并保存到系统密钥库。

• tencent_docs_openapi_logout：删除本机用户 Token，保留用户自己的应用配置。

• tencent_docs_openapi_set_starred、tencent_docs_openapi_set_pinned：收藏和置顶。

• tencent_docs_openapi_set_watermark：设置文字水印和访客水印。

• tencent_docs_openapi_create_shortcut、tencent_docs_openapi_recover_file：快捷方式和回收站恢复。

• tencent_docs_openapi_get_user_access：读取当前用户的详细访问能力。

• tencent_docs_openapi_get_file_permission：读取完整分享策略、复制和批注开关。

• tencent_docs_openapi_get_folder_permission：读取用户对文件夹的查看、编辑、分享和添加成员能力。

• tencent_docs_openapi_transfer_ownership：转让所有权，要求精确确认词。

• tencent_docs_openapi_set_file_permission：设置分享策略、复制下载打印和只读批注开关。

• tencent_docs_openapi_apply_file_permission：申请查看或编辑权限。

• tencent_docs_openapi_add_collaborators、tencent_docs_openapi_remove_collaborator、tencent_docs_openapi_list_collaborators：协作成员管理。

• tencent_docs_openapi_filter_files：按目录、类型、所有者和排序条件读取文件。

• tencent_docs_openapi_convert_file_id：在 fileID 与 encodedID 之间转换。

• tencent_docs_openapi_get_usage、tencent_docs_openapi_get_unread_count：应用使用量与未读消息。

• tencent_docs_openapi_set_form_release：发布、暂停或设置收集截止时间。

• tencent_docs_openapi_generate_form_result：生成收集结果表格。

• tencent_docs_openapi_batch_insert_sheet_images：一次插入最多 500 张表格图片。

调用示例见 docs/OpenAPI使用示例.md，工具来源和实测边界见 docs/能力矩阵.md。

写入工具会完整替换现有题目。使用前建议先复制一份表单进行测试。

登录方式

Windows 推荐使用 browser_login.py。浏览器只负责让你本人登录；登录完成后会自动关闭，后续创建、编辑、发布全部直接调用接口，不会操控浏览器。登录状态保存在 %LOCALAPPDATA%\TencentDocsFormMCP\auth.bin，内容受 Windows 当前账号加密保护。

Windows MCP 配置：

TENCENT_DOCS_USE_SAVED_LOGIN=1

其他系统仍可显式选择浏览器 Cookie：

TENCENT_DOCS_USE_BROWSER_COOKIES=1
TENCENT_DOCS_BROWSER=chrome

TENCENT_DOCS_BROWSER 支持 brave、chrome、chromium、edge、firefox、vivaldi。这条旧方式读取浏览器自身的 Cookie；Windows 新登录助手不会受新版 Chrome/Edge Cookie 加密方式影响。

也支持通过进程环境变量 TENCENT_DOCS_COOKIE 提供 Cookie header，但不要把 Cookie 写进仓库、配置示例或聊天消息。

作为 Skill 使用

SKILL.md 提供了 Agent 的调用规则。MCP 负责真正连接腾讯文档；Skill 只告诉 AI 应该何时调用哪个工具、如何检查结果。因此只复制 Skill、没有启动 MCP，不能编辑腾讯文档。

开发与测试

python -m pip install -r requirements.txt
python -m unittest discover -s tests -v

GitHub Actions 会在 Ubuntu、macOS、Windows，以及 Python 3.10 和 3.13 上执行测试。自动测试不包含真实腾讯账号。详细范围见 docs/能力矩阵.md。

安全说明

• Windows 登录助手将 Cookie 写入当前账号才能解密的系统加密文件，不会写入项目或工具返回值。

• 仅表单创建者或管理员可以写入和发布。

• 项目不会绕过腾讯文档登录、访问权限或提交限制。

• 安全问题请参阅 SECURITY.md。

许可证

MIT