coda

coda-mcp

用于 Coda.io API 的 MCP（Model Context Protocol）服务。支持 AI 助手读取和写入 Coda 文档、表格和行。

功能

• 对 Coda 表格执行完整的 CRUD 操作
• 获取文档和页面内容
• 访问公式和控件
• 画布页面的异步导出工作流
• 速率限制处理

快速开始

1. 安装

cargo install coda-mcp

2. 获取 API 令牌

从 coda.io/account → API 设置中获取令牌。

3. 配置 Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 ~/.config/claude/claude_desktop_config.json（Linux）：

{
  "mcpServers": {
    "coda": {
      "command": "/Users/YOUR_USERNAME/.cargo/bin/coda-mcp",
      "env": {
        "CODA_API_TOKEN": "your_token_here"
      }
    }
  }
}

4. 重启 Claude Desktop

现在即可使用 Coda 工具。

安装

从 crates.io 安装（推荐）

cargo install coda-mcp

从源代码构建

git clone https://github.com/nkpar/coda-mcp.git
cd coda-mcp
cargo build --release

二进制文件位于 ./target/release/coda-mcp

预构建二进制文件

请查看 Releases 页面。

Docker

无需 Rust 工具链。多架构镜像（amd64 + arm64），约 3MB。

docker pull ghcr.io/nkpar/coda-mcp:latest

Claude Code（命令行）：

claude mcp add coda -e CODA_API_TOKEN=your_token_here -- docker run --rm -i -e CODA_API_TOKEN ghcr.io/nkpar/coda-mcp:latest

Claude Desktop 配置：

{
  "mcpServers": {
    "coda": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "CODA_API_TOKEN", "ghcr.io/nkpar/coda-mcp:latest"],
      "env": {
        "CODA_API_TOKEN": "your_token_here"
      }
    }
  }
}

一键安装脚本

适用于 Claude Desktop，可自动完成配置：

git clone https://github.com/nkpar/coda-mcp.git
cd coda-mcp
./scripts/install.sh

配置

1. 获取 API 令牌

从 coda.io/account → API 设置中获取 Coda API 令牌。

重要： 对于写入操作（create_doc、delete_doc、add_row、update_row、delete_row），请确保令牌已启用写入权限。只读令牌执行这些操作时会返回 403 Forbidden。

2. 配置 MCP 客户端

Claude Desktop（~/.config/claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "coda": {
      "command": "/path/to/coda-mcp",
      "env": {
        "CODA_API_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Code（命令行）：

# Binary
claude mcp add coda -e CODA_API_TOKEN=your_token_here -- $HOME/.cargo/bin/coda-mcp

# Or via Docker (no Rust required)
claude mcp add coda -e CODA_API_TOKEN=your_token_here -- docker run --rm -i -e CODA_API_TOKEN ghcr.io/nkpar/coda-mcp:latest

或者在项目根目录的 .mcp.json 中配置：

{
  "mcpServers": {
    "coda": {
      "command": "/path/to/coda-mcp",
      "env": {
        "CODA_API_TOKEN": "your_token_here"
      }
    }
  }
}

环境变量

变量	必需	描述
CODA_API_TOKEN	是	你的 Coda API 令牌
CODA_BASE_URL	否	API 基础 URL（默认值：https://coda.io/apis/v1）
RUST_LOG	否	日志级别：error、warn、info、debug、trace

工具

工具	描述
list_docs	列出可用文档
get_doc	获取文档详情
search_docs	按名称搜索文档
create_doc	创建新文档（可选：文件夹、模板、时区）
delete_doc	删除文档（永久）
list_pages	列出文档中的页面
get_page	获取页面内容（HTML）
list_tables	列出文档中的表格
get_table	获取表格详情
list_columns	列出表格中的列
get_rows	获取行，可选进行筛选
get_row	获取指定行
add_row	添加新行
update_row	更新现有行
delete_row	删除行
list_formulas	列出命名公式
get_formula	获取公式值
list_controls	列出控件（按钮、滑块）

使用示例

# List all documents
list_docs

# Create a new document
create_doc title="My New Doc"

# Create from template in specific folder
create_doc title="Project Plan" folder_id="fl-abc" source_doc="template-xyz"

# Delete a document (permanent!)
delete_doc doc_id="AbCdEfGh"

# Get rows from a table
get_rows doc_id="AbCdEfGh" table_id="grid-xyz" limit=50

# Filter rows
get_rows doc_id="AbCdEfGh" table_id="grid-xyz" query="Status:Active"

# Add a row
add_row doc_id="AbCdEfGh" table_id="grid-xyz" cells={"Name": "John", "Email": "[email protected]"}

# Get page content
get_page doc_id="AbCdEfGh" page_id="canvas-xyz"

速率限制

Coda API 有速率限制：

• 读取：每 6 秒 100 个请求
• 写入：每 6 秒 10 个请求

写入操作会返回 HTTP 202（已排队）。更改可能需要几秒钟才会显示。

安全

• 所有日志输出中的 API 令牌都会被隐藏
• 下载 URL 仅允许来自可信主机（coda.io、codahosted.io、storage.googleapis.com）
• 请求数量上限为 1000，以防止资源耗尽
• 安装脚本会以静默方式输入令牌，并设置严格的文件权限（600）

开发

# Build
cargo build --release

# Run unit & integration tests
cargo test

# Run E2E tests (requires write-enabled API token)
export $(cat .env | xargs) && cargo test --test e2e_tests -- --ignored

# Run with debug logging
RUST_LOG=debug cargo run

# Format & lint
cargo fmt && cargo clippy

API 详情请参阅 DEVELOPER.md，贡献指南请参阅 CONTRIBUTING.md。

许可证

MIT 许可证。详情请参阅 LICENSE。