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) サーバーです。Coda API を通じて、AI アシスタントが 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 は、一般に MCP 2.0 と呼ばれる Model Context Protocol 2026-07-28 仕様を実装しています。また、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、レート制限、または読み取り専用ガードに阻まれる書き込み）は、呼び出し側が error キーを確認する必要のある値ではなく、isError: true を含むツール結果として返されます。（ロックされた読み取り専用モードでは書き込みツールは非表示になるため、それを呼び出すと Unknown tool エラーが返されます。以下のエンベロープはガード自体の応答で、クライアントが何らかの方法で書き込みツールに到達した場合にのみ返されます。）結果の本文はテキストコンテンツであり、error、実行可能な対処を示す hint、および該当する場合は status_code、body、retry_after を含む JSON オブジェクトです。結果には structuredContent は含まれません。TypeScript MCP SDK は isError が true の場合でも structuredContent をツールの出力スキーマに照らして検証するため、そこにエラーペイロードがあると、厳格なクライアントは結果全体を拒否します。予期しない例外（ツール内のバグ）も isError: true となり、そのテキストは TypeName: message です。サーバーはトレースバックとともに例外をログに記録します。

成功した結果では、Coda JSON オブジェクトが整形済みテキストのほかに structuredContent として含まれます。また、ツールは 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 はロックを強めることしかできません。ロックの強度は起動環境次第です。ユーザーが編集できない場所（Claude Code の managed-mcp.json などの管理対象 MCP 設定、コンテナー、k8s または systemd の環境変数、ホスト型 HTTP デプロイ）で設定してください。ユーザー自身がサーバーを起動する場合、その環境はユーザーが制御します。Coda トークンにはスコープがないため、このロックが唯一の読み取り専用制御です。
• MCP ツールのアノテーション：各ツールは、クライアント側の権限確認プロンプト向けに readOnlyHint、destructiveHint、idempotentHint を宣言します。
• 認証情報の保存なし：サーバーはトークンを永続化しません。起動時に環境変数から認証情報を読み込みます。
• HTTP トランスポートの認証：Host／Origin 保護は認証ではありません。HTTP トランスポートをループバック以外のホストにバインドするには、CODA_HTTP_BEARER_TOKEN（16 文字以上）が必要です。クライアントは Authorization: Bearer <token> を送信し、それ以外は 401 を返します。これが設定されていない場合、サーバーはループバック以外のホストでの起動を拒否します。

0.9.0 へのアップグレード

デフォルト値が 2 つ変更されました。以前の動作に依存していた呼び出し元には、どちらも互換性のない変更です。

• coda_publish_doc は、デフォルトでドキュメントを公開ギャラリーに掲載しなくなりました。 discoverable のデフォルトは False になりました。公開するとドキュメントは URL からアクセス可能になりますが、Coda ギャラリーに掲載するには discoverable=True を渡してください。mode は view、play、edit のいずれかに制限されます。
• ループバック以外のホストで HTTP トランスポートを使用する場合、ベアラートークンが必須になりました。 uvx mcp-coda --transport streamable-http --host 0.0.0.0（またはループバック以外の任意のホスト）は、CODA_HTTP_BEARER_TOKEN（16 文字以上）が設定されていないとエラーで終了します。その場合、クライアントは Authorization: Bearer <token> を送信します。127.0.0.1 へのバインドに変更はありません。

レート制限と権限

レート制限

Coda はトークンごとにレート制限を適用します（プランによって異なります）。Coda がリクエストをレート制限すると、ツールは retry_after 秒を含む 429 エラーを返します。クライアントは Retry-After が 5 秒以下の場合、429 に対して 1 回再試行します（GET のみ、ジッターを含み、502／503／504 も対象）。それ以外の場合は再試行せず、retry_after を返します。その秒数待ってから再試行してください。書き込みは再試行されません。ページ分割に対応するほとんどのエンドポイントでは、1 ページあたりの結果数はデフォルトで 50 件です（coda_list_docs は 25 件、coda_list_columns は 100 件）。limit で調整してください。

非同期ミューテーション

Coda は書き込み操作（行の挿入、更新、削除）を非同期で処理します。ツールは requestId を返します。coda_get_mutation_status で確認し、完了したことを確かめてください。

必要な権限

アクセス制御

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 とシェルの履歴に露出します。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

FAQ

mcp-coda は MCP 2.0（2026-07-28 仕様）に対応していますか？

はい。mcp-coda は、一般に MCP 2.0 と呼ばれる MCP 2026-07-28 仕様を実装しています。また、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 はホスト型サービスであるため、セルフホスト型のデプロイはありません。CODA_BASE_URL は、プロキシまたはデフォルト以外の API ベースを対象にする場合にのみ設定してください。

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