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 に生成されます。

ビルド済みバイナリ

リリースページを確認してください。

Docker

Rust ツールチェーンは不要です。マルチアーキテクチャイメージ（amd64 + arm64）で、サイズは約3MBです。

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

Claude Code（CLI）：

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（CLI）：

# 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 を参照してください。