内容
# coda-mcp
<a href="https://registry.modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Registry-blue" alt="MCP Registry"></a>
<a href="https://crates.io/crates/coda-mcp"><img src="https://img.shields.io/crates/v/coda-mcp.svg" alt="Crates.io"></a>
<a href="https://github.com/nkpar/coda-mcp/actions/workflows/ci.yml"><img src="https://github.com/nkpar/coda-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://codecov.io/gh/nkpar/coda-mcp"><img src="https://codecov.io/gh/nkpar/coda-mcp/graph/badge.svg" alt="codecov"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
<a href="https://www.rust-lang.org"><img src="https://img.shields.io/badge/MSRV-1.93-orange.svg" alt="MSRV"></a>
MCP (Model Context Protocol) server for [Coda.io](https://coda.io) API. 能够让AI助手读取和写入Coda文档、表格和行。
## 功能
- 对Coda表格的完整CRUD操作
- 文档和页面内容检索
- 公式和控件访问
- 用于画布页面的异步导出工作流
- 速率限制处理
## 快速开始
### 1. 安装
```bash
cargo install coda-mcp
```
### 2. 获取 API Token
从 [coda.io/account](https://coda.io/account) → API 设置获取您的token。
### 3. 配置 Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 或 `~/.config/claude/claude_desktop_config.json` (Linux):
```json
{
"mcpServers": {
"coda": {
"command": "/Users/YOUR_USERNAME/.cargo/bin/coda-mcp",
"env": {
"CODA_API_TOKEN": "your_token_here"
}
}
}
}
```
### 4. 重启 Claude Desktop
Coda工具现在可以使用了。
## 安装
### 从 crates.io (推荐)
```bash
cargo install coda-mcp
```
### 从源码
```bash
git clone https://github.com/nkpar/coda-mcp.git
cd coda-mcp
cargo build --release
```
二进制文件将在 `./target/release/coda-mcp`
### 预构建的二进制文件
查看 [Releases](https://github.com/nkpar/coda-mcp/releases) 页面。
### Docker
无需Rust工具链。多架构镜像 (amd64 + arm64)，约3MB。
```bash
docker pull ghcr.io/nkpar/coda-mcp:latest
```
**Claude Code** (CLI):
```bash
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** 配置:
```json
{
"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，具有自动配置功能：
```bash
git clone https://github.com/nkpar/coda-mcp.git
cd coda-mcp
./scripts/install.sh
```
## 配置
### 1. 获取 API Token
从 [coda.io/account](https://coda.io/account) → API 设置获取您的Coda API token。
**重要提示：** 对于写入操作 (`create_doc`, `delete_doc`, `add_row`, `update_row`, `delete_row`)，请确保您的token已启用写入权限。只读token将为这些操作返回403 Forbidden。
### 2. 配置 MCP Client
**Claude Desktop** (`~/.config/claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"coda": {
"command": "/path/to/coda-mcp",
"env": {
"CODA_API_TOKEN": "your_token_here"
}
}
}
}
```
**Claude Code** (CLI):
```bash
# 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`:
```json
{
"mcpServers": {
"coda": {
"command": "/path/to/coda-mcp",
"env": {
"CODA_API_TOKEN": "your_token_here"
}
}
}
}
```
### 环境变量
| Variable | Required | Description |
|----------|----------|-------------|
| `CODA_API_TOKEN` | Yes | 您的 Coda API token |
| `CODA_BASE_URL` | No | API base URL (默认: `https://coda.io/apis/v1`) |
| `RUST_LOG` | No | 日志级别: `error`, `warn`, `info`, `debug`, `trace` |
## 工具
| Tool | Description |
|------|-------------|
| `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": "john@example.com"}
# Get page content
get_page doc_id="AbCdEfGh" page_id="canvas-xyz"
```
## 速率限制
Coda API 有速率限制:
- **读取**: 每 6 秒 100 个请求
- **写入**: 每 6 秒 10 个请求
写入操作返回 HTTP 202 (已排队)。更改可能需要几秒钟才能显示。
## 安全
- API token从所有日志输出中删除
- 下载 URL 仅针对受信任的主机进行验证 (coda.io, codahosted.io, storage.googleapis.com)
- 请求限制上限为 1000，以防止资源耗尽
- 安装脚本对token使用静默输入，并设置限制性文件权限 (600)
## 开发
```bash
# 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](DEVELOPER.md)，有关贡献指南，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
MIT License. 有关详细信息，请参见 [LICENSE](LICENSE)。
