PDF 工具箱 MCP 接入说明

English

PDF 工具箱是一个面向 Agent 的 MCP 文件处理服务，通过 Streamable HTTP 提供 PDF/图片转 Word、Excel、Markdown、PDF 拆分合并、图片转 PDF、文字水印和异步任务查询能力。支持 OAuth 和手动 API Key 两种授权方式。

1. 快速选择

2. 固定配置

3. OAuth：豆包推荐方式

在豆包中按以下步骤操作：

1. 在远程 MCP/Connector 中填写：

   text

   Copy

   https://api.tensormaster.com/pdf/mcp
   

2. 点击“去授权”

3. 浏览器打开 MiaoDashi 授权页面；首次使用先注册，已有账号直接登录。

4. 核对客户端名称、PDF 工具箱和权限范围，点击“同意授权”。

5. 页面返回豆包后，确认状态显示“授权成功”或“已连接”。

DCR、state、PKCE、授权码兑换、Access Token 和 Refresh Token 均由豆包与 MiaoDashi 自动完成，用户无需手动复制授权码或 Token。Access Token 过期后，豆包使用 Refresh Token 自动续期。

Claude 接入步骤

将以下指令发送给 Claude：

帮我在设置里添加一个新的 MCP 连接器，地址是 https://api.tensormaster.com/pdf/mcp。添加后提醒我确认授权页面上的权限范围，再点同意。

然后按以下步骤完成授权：

1. 退出 Claude，再重新进入 Claude。
2. 输入 /mcp，选择 PDF 服务并进行授权。
3. 确认授权成功后，即可使用 PDF 工具箱。

Codex（ChatGPT）接入步骤

1. 打开 设置 → 插件 → 添加 → 添加 MCP 服务器。

2. 填写：

   text

   Copy

   名称：pdf
   类型：流式 HTTP
   URL：https://api.tensormaster.com/pdf/mcp
   

3. 点击“保存”。

4. 点击“进行身份验证”，注册或登录 MiaoDashi 网站，并在授权页面确认权限后点击“同意”。

5. 返回设置页，确认“进行身份验证”按钮消失，即表示授权成功，可以使用 PDF 工具箱。

ChatGPT 的菜单名称可能因账号、工作区权限或版本略有差异；如果看不到添加 MCP 服务器入口，请先确认已启用相应的开发者模式或自定义连接器权限。

4. 手动 API Key：兼容方式

4.1 获取 API Key

1. 打开 MiaoDashi API Keys，登录需要承担 PDF 费用的账号。
2. 点击“创建 API Key”，填写名称，例如 pdf-mcp-local。
3. 选择 PDF 工具需要的最小权限，至少需要文件处理/生成权限；按需设置过期时间。
4. 创建成功后立即复制完整 Key。完整 Key 通常只显示一次，请保存到密码管理器或 MCP Client 安全存储。

不要使用网页内部 Key、OAuth Token、Device Flow Key 或其他服务的 Key。

4.2 配置 MCP Client

MCP Gateway 已启用手动 Key 兼容入口时，使用：

{
  "mcpServers": {
    "pdf-toolkit": {
      "type": "streamableHttp",
      "url": "https://api.tensormaster.com/pdf/mcp",
      "headers": {
        "Authorization": "Bearer md_api_<your_key>"
      }
    }
  }
}

也可以直接发送：

Authorization: Bearer md_api_<your_key>

不要把 API Key 放到 URL、Query、日志或聊天内容中。先调用 get_pdf_toolbox_capabilities 验证连接，再提交转换任务。

5. 工具列表

参数和任务规则

• MCP 请求使用 JSON-RPC，不接收 multipart/form-data。
• 用户附件必须映射为临时 HTTPS URL：单文件使用 file_url，多文件使用 file_urls 或 image_urls。
• split_pdf.pages_per_file 为 1..50；merge_pdfs 支持 2～10 个文件；images_to_pdf 支持 1～10 张图片；scale 为 (0, 1]。
• 创建任务必须使用 idempotency_key；相同参数重试不会重复创建或扣费。
• 任务状态：queued → running → succeeded/failed。使用 get_pdf_task 轮询，不要重复创建任务。
• 任务只能由所属用户查询。

6. 常见错误

7. 安全要求

• 全部 MCP、OAuth、Token 和发现地址使用 HTTPS。
• Access Token、Refresh Token 和 API Key 只能放在 Authorization Header。
• 不要记录完整凭据、内部 JWT、Supabase 密钥或签名下载 URL。
• 文件 URL 必须经过 HTTPS、大小、重定向、DNS/IP 和超时校验，防止 SSRF。
• 怀疑 API Key 泄露时，立即在 MiaoDashi API Keys 页面撤销并重新创建。