mcp-coda

mcp-coda

安装： uvx mcp-coda | PyPI | MCP Registry | 更新日志

uvx mcp-coda                          # with writes
MCP_READ_ONLY=true uvx mcp-coda       # locked read-only: write tools are not listed

mcp-coda 是一个用于 Coda 的 Model Context Protocol (MCP) 服务。它让 AI 助手通过 Coda API 读取和写入 Coda 文档、页面、表格和行。它还可以运行公式、管理权限和文件夹、发布文档并触发自动化。该服务提供 54 个工具、12 个资源和 5 个提示词。它支持 MCP 2026-07-28 规范（通常称为 MCP 2.0），并与 2025-11-25 客户端保持兼容。它适用于 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot 以及任何兼容 MCP 的客户端。支持两种运行模式：允许写入，或锁定为只读（MCP_READ_ONLY=true），此时不会向模型提供 20 个写入工具。

mcp-coda 使用 FastMCP、httpx 和 Pydantic。

一键安装

提示： 对于其他 AI 助手（Claude Code、Windsurf、IntelliJ、Gemini CLI），请访问 Coda MCP 安装入口。

# with writes
claude mcp add coda -e CODA_API_TOKEN=your-token-here -- uvx mcp-coda
# locked read-only
claude mcp add coda -e MCP_READ_ONLY=true -e CODA_API_TOKEN=your-token-here -- uvx mcp-coda

{
  "mcpServers": {
    "coda": {
      "command": "uvx",
      "args": ["mcp-coda"],
      "env": {
        "CODA_API_TOKEN": "your-token-here",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
gemini mcp add -s user -e CODA_API_TOKEN=your-token-here coda uvx mcp-coda
# locked read-only
gemini mcp add -s user -e MCP_READ_ONLY=true -e CODA_API_TOKEN=your-token-here coda uvx mcp-coda

{
  "servers": {
    "coda": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-coda"],
      "env": { "CODA_API_TOKEN": "your-token-here", "MCP_READ_ONLY": "true" }
    }
  }
}

# with writes
codex mcp add coda --env CODA_API_TOKEN=your-token-here -- uvx mcp-coda
# locked read-only
codex mcp add coda --env MCP_READ_ONLY=true --env CODA_API_TOKEN=your-token-here -- uvx mcp-coda

uv pip install mcp-coda

支持的令牌类型

服务按以下顺序检查这些环境变量——以第一个匹配项为准：

1. CODA_API_TOKEN
2. CODA_TOKEN
3. CODA_PAT

在 coda.io/account#apiSettings 生成令牌。令牌可访问其所有者能够访问的全部文档。令牌没有范围限制。文档级访问权限由 Coda 的共享设置控制。

兼容性

协议支持

mcp-coda 实现了 Model Context Protocol 2026-07-28 规范，通常称为 MCP 2.0。它也继续兼容 2025-11-25 客户端。固定使用 2026-07-28 的 FastMCP 客户端和旧版客户端都能列出所有工具，并通过 stdio 调用 Coda API。配套的代码 PR 添加了一项回归测试，用固定使用 2026-07-28 的内存客户端检查 tools/list。

• 规范版本：MCP 2026-07-28（MCP 2.0），向后兼容 2025-11-25。
• 基于：FastMCP 4.x 和 MCP Python SDK 2.x。
• 传输方式：stdio（默认）和 streamable-http（远程连接推荐）。sse（HTTP+SSE）仍可使用，但 2026-07-28 规范已弃用该方式，因此服务会打印警告。
• 功能：工具、资源和提示词。服务不使用 Roots、Sampling、Logging、elicitation 或资源订阅，因此 2026-07-28 的弃用事项不会影响它。

错误结果

预期的失败情况——404、401、速率限制，或因触发只读保护而被拦截的写入操作——会作为带有 isError: true 的工具结果返回，而不是要求调用方检查是否存在 error 键的值。（在锁定的只读模式下，写入工具会被隐藏，因此调用其中一个会返回 Unknown tool 错误；下方的错误封装是保护机制本身的响应，仅当客户端仍然调用写入工具时才会返回。）结果正文是文本内容：一个包含 error、可操作的 hint，以及视情况而定的 status_code、body 和 retry_after 的 JSON 对象。结果不包含 structuredContent——TypeScript MCP SDK 会根据工具的输出架构验证 structuredContent，即使 isError 为 true 也是如此，因此将错误载荷放在那里会导致严格客户端拒绝整个结果。意外异常（工具中的 Bug）也会以 isError: true 返回，文本格式为 TypeName: message，并且服务端会记录异常及其回溯信息。

成功的结果会在格式化文本旁的 structuredContent 中携带 Coda JSON 对象，且工具不声明 outputSchema：载荷会以无类型方式传递上游字段，因此严格客户端不会验证任何内容，并会直接收到该对象，而不是收到双重编码的 {"result": "<json>"} 封装。可通过每个工具上的 @mcp.tool(output_schema=…) 选择启用类型化架构。

工具（54）

资源（12）

该服务提供 MCP 资源，用于提供环境上下文，且不会消耗工具调用。

数据资源（实时 API）

规则（静态知识）

指南（操作方法）

提示词（5）

该服务器提供 MCP 提示词——可供客户端调用的可复用任务模板。

使用示例

文档和页面

"List all my Coda docs"
→ coda_list_docs(is_owner=True)

"Get the content of page 'Sprint Planning' in doc d1"
→ coda_list_pages(doc_id="d1") → find page ID
→ coda_get_page_content(doc_id="d1", page_id_or_name="canvas-abc")

"Create a new doc from a template"
→ coda_create_doc(title="Q1 Planning", source_doc="template-doc-id")

表格和行

"List all tables in doc d1"
→ coda_list_tables(doc_id="d1")

"Find rows where Status is 'Done'"
→ coda_list_rows(doc_id="d1", table_id_or_name="Tasks", query="Done")

"Insert a new row into the Tasks table"
→ coda_insert_rows(doc_id="d1", table_id_or_name="Tasks", rows=[{"cells": [{"column": "Name", "value": "New task"}]}])

"Update a row's status"
→ coda_update_row(doc_id="d1", table_id_or_name="Tasks", row_id_or_name="i-abc", row={"cells": [{"column": "Status", "value": "In Progress"}]})

公式和控件

"Get the value of the TotalBudget formula"
→ coda_get_formula(doc_id="d1", formula_id_or_name="TotalBudget")

"Check the current value of the DateFilter control"
→ coda_get_control(doc_id="d1", control_id_or_name="DateFilter")

权限和共享

"Share a doc with a teammate"
→ coda_add_permission(doc_id="d1", access="write", principal_email="[email protected]")

"List who has access to a doc"
→ coda_list_permissions(doc_id="d1")

安全注意事项

• 令牌范围：Coda API 令牌可以访问令牌所有者有权访问的所有文档。生产部署时请使用专用服务账户，以限制暴露范围。
• 只读模式：在你控制的启动配置中设置 MCP_READ_ONLY=true（或 CODA_READ_ONLY=true），服务器启动后便会锁定：不会列出 20 个写入工具和写入工作流提示词，调用它们会返回“Unknown tool”，且保护机制会拒绝任何仍到达服务器的写入操作。运行时无法解除锁定——其他来源提供的 false、.env 文件或工具参数都不行；除 false/0/no/off/空值以外的任何值都会锁定，而 --read-only 只能启用锁定。锁定强度取决于启动配置：请在用户无法编辑的位置设置该选项（例如受管理的 MCP 配置，如 Claude Code managed-mcp.json、容器、k8s 或 systemd 环境变量，或托管的 HTTP 部署）。自行启动服务器的用户可以控制其环境。Coda 令牌没有权限范围，因此此锁定是唯一的只读控制措施。
• MCP 工具注释：每个工具都声明 readOnlyHint、destructiveHint 和 idempotentHint，供客户端侧权限提示使用。
• 不存储凭据：服务器不会持久化令牌。它会在启动时从环境变量读取凭据。
• HTTP 传输身份验证：Host/Origin 保护不等同于身份验证。将 HTTP 传输绑定到非回环主机时，必须设置 CODA_HTTP_BEARER_TOKEN（至少 16 个字符）；客户端发送 Authorization: Bearer <token>，其他任何内容都会得到 401 响应。未设置时，服务器会拒绝在非回环主机上启动。

升级到 0.9.0

两项默认值已更改。对于依赖旧行为的调用方，这两项更改都会造成破坏性影响：

• coda_publish_doc 默认不再将文档列入公共图库。 discoverable 现在默认为 False——仅发布文档会使其可通过 URL 访问；传入 discoverable=True 可将其列入 Coda 图库。mode 现在仅限 view、play 或 edit。
• 现在，在非回环主机上使用 HTTP 传输必须提供承载令牌。 如果未设置 CODA_HTTP_BEARER_TOKEN（至少 16 个字符），uvx mcp-coda --transport streamable-http --host 0.0.0.0（或任何非回环主机）将报错退出；客户端随后发送 Authorization: Bearer <token>。绑定到 127.0.0.1 的行为不变。

速率限制和权限

速率限制

Coda 会对每个令牌实施速率限制（具体限制因套餐而异）。当 Coda 对请求进行速率限制时，工具会返回一个 429 错误，并附带 retry_after 秒数。当 Retry-After 小于或等于 5 秒时，客户端会对 429 重试一次（仅限 GET 请求，并加入随机抖动；也适用于 502/503/504）；否则会直接返回 retry_after，不进行重试——等待相应秒数后再重试。写入操作绝不会重试。大多数分页端点默认每页返回 50 条结果（coda_list_docs 为 25 条，coda_list_columns 为 100 条）。使用 limit 调整数量。

异步变更

Coda 会异步处理写入操作（插入、更新、删除行）。工具会返回一个 requestId。使用 coda_get_mutation_status 检查该 ID，以确认操作已完成。

所需权限

访问控制

CLI 和传输选项

# Default: stdio transport (for MCP clients)
uvx mcp-coda

# HTTP transport (SSE or streamable-http)
uvx mcp-coda --transport sse --host 127.0.0.1 --port 8000
uvx mcp-coda --transport streamable-http --port 9000

# Binding to a non-loopback host requires a bearer token
CODA_HTTP_BEARER_TOKEN=$(openssl rand -hex 32) \
  uvx mcp-coda --transport streamable-http --host 0.0.0.0 --port 9000
# Clients authenticate with the token:
#   curl -H "Authorization: Bearer $CODA_HTTP_BEARER_TOKEN" http://host:9000/mcp

# Config comes from env vars
CODA_API_TOKEN=your-token uvx mcp-coda --read-only

--coda-token 仍可使用，但已弃用并从 --help 中隐藏：它会使令牌暴露在 ps 和 shell 历史记录中。请使用 CODA_API_TOKEN。

服务器会通过 python-dotenv 自动从工作目录加载 .env 文件。

Docker

此映像采用精简的非 root python:3.13-slim 构建。映像默认锁定为只读（MCP_READ_ONLY=true）；传入 -e MCP_READ_ONLY=false 即可允许写入。

docker build -t mcp-coda .

# stdio (default), locked read-only
docker run -i --rm -e CODA_API_TOKEN=your-token mcp-coda

# HTTP transport on a non-loopback host requires a bearer token (min 16 chars);
# clients then send Authorization: Bearer <token>
BEARER=$(openssl rand -hex 32)
docker run --rm -p 9000:9000 \
  -e CODA_API_TOKEN=your-token \
  -e CODA_HTTP_BEARER_TOKEN="$BEARER" \
  mcp-coda --transport streamable-http --host 0.0.0.0 --port 9000

常见问题

mcp-coda 是否支持 MCP 2.0（2026-07-28 规范）？

支持。mcp-coda 实现了 MCP 2026-07-28 规范，通常称为 MCP 2.0。它也兼容 2025-11-25 客户端。

mcp-coda 支持哪些传输方式？

服务器支持 stdio（默认）和 streamable-http。它也支持 sse，但 2026-07-28 规范已弃用该方式。远程连接建议使用 streamable-http。

我能否以只读模式运行 mcp-coda，防止助手进行任何更改？

可以。使用 MCP_READ_ONLY=true（或 CODA_READ_ONLY=true）启动。此时，20 个写入工具和写入工作流提示词都不会列出，因此模型看不到它们；调用其中任何工具都会返回“Unknown tool”，且进程运行期间无法重新启用写入功能。请在由你控制的启动配置中设置该变量，例如受管理的 MCP 配置、容器或 systemd 环境变量，或者托管部署；因为自行启动服务器的用户可以不设置该变量。Coda 令牌没有作用域，因此此锁定是唯一的只读控制方式。

mcp-coda 需要哪些令牌作用域？

Coda 令牌没有作用域。令牌可以访问其所有者能够访问的每个文档。文档级访问权限由 Coda 的共享设置控制。请使用专用服务账号来限制暴露范围。

mcp-coda 是否适用于可自托管的 Coda？

Coda 是托管服务，因此没有可自托管的部署方式。仅在需要指定代理或非默认 API 基础地址时，才设置 CODA_BASE_URL。

哪些客户端适用于 mcp-coda？

mcp-coda 适用于 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot，以及任何通过 stdio 或 HTTP 兼容 MCP 的客户端。

它提供多少个工具、资源和提示词？

mcp-coda 提供 54 个工具、12 个资源和 5 个提示词，涵盖文档、页面、表格、行、公式、控件、权限、文件夹、发布、自动化和分析数据。

相关 MCP 服务

• mcp-gitlab — GitLab 集成（83 个工具、7 个资源、6 个提示词）
• mcp-atlassian-extended — Jira + Confluence 集成（22 个工具、15 个资源、5 个提示词）
• mcp-argocd — Argo CD 集成（37 个工具、7 个资源、7 个提示词）

开发

git clone https://github.com/vish288/mcp-coda.git
cd mcp-coda
uv sync --all-extras

uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

许可证

MIT