Seatable Mcp

SeaTable MCP

SeaTable の公式 Model Context Protocol（MCP）サーバーです。SeaTable GmbH が構築し、保守しています。AI エージェントが、ツールを厳選したセットを使って、ベース内のデータの読み取り、書き込み、検索、リンク、行のクエリを行えるようにします。このサーバーは意図的にデータ操作に焦点を当てており、スキーマ管理（テーブルや列の作成・削除）は対象外としています。これにより、ツールセットを簡潔に保ち、自律型エージェントでも安全に使用できます。

クイックスタート

最も手早く始める方法は、環境によって異なります。

• SeaTable Cloud — ホスト型 MCP サーバー mcp.seatable.com を使用します。インストールは不要です
• セルフホスト型 SeaTable — IDE で npx を使って MCP サーバーをローカルで実行します

SeaTable Cloud（ホスト型 MCP サーバー）

SeaTable Cloud を使用している場合は、すぐに使えるホスト型 MCP サーバーがあります。インストールは不要です。Streamable HTTP エンドポイントを使用するように MCP クライアントを設定します。

Claude Desktop — claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "seatable": {
      "type": "streamable-http",
      "url": "https://mcp.seatable.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      }
    }
  }
}

Cursor / VSCode — MCP 設定（JSON）に追加します。

{
  "mcp.servers": {
    "seatable": {
      "type": "streamable-http",
      "url": "https://mcp.seatable.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      }
    }
  }
}

ChatGPT およびその他の OAuth 対応クライアント — 組み込みの OAuth フローを使用します。ChatGPT の開発者モードで、次のように設定します。

• サーバー URL： https://mcp.seatable.com/mcp
• 認証タイプ： OAuth
• 認証 URL： https://mcp.seatable.com/authorize
• トークン URL： https://mcp.seatable.com/token

認証手順で SeaTable API トークンの入力を求められます。

セルフホスト型 SeaTable

セルフホスト型 SeaTable インスタンスの場合は、npx を使って MCP サーバーをローカルで実行します。IDE がプロセスを自動的に起動し、管理します。

Claude Desktop — claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "seatable": {
      "command": "npx",
      "args": ["-y", "@seatable/mcp-seatable"],
      "env": {
        "SEATABLE_SERVER_URL": "https://your-seatable-server.com",
        "SEATABLE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cursor / VSCode — MCP 設定（JSON）に追加します。

{
  "mcp.servers": {
    "seatable": {
      "command": "npx",
      "args": ["-y", "@seatable/mcp-seatable"],
      "env": {
        "SEATABLE_SERVER_URL": "https://your-seatable-server.com",
        "SEATABLE_API_TOKEN": "your-api-token"
      }
    }
  }
}

デプロイオプション

たとえば、自社のインフラストラクチャ上で、複数のベースに対応させたり、マルチテナントモードで実行したりするために、独自のサーバーインスタンスが必要な場合は、以下のいずれかの方法を使用してください。

HTTP サーバー（ネットワークアクセス）

Streamable HTTP トランスポートを使用して、ローカル HTTP サーバーを実行します。

PORT=3001 npx -y @seatable/mcp-seatable --sse

# Health check
curl http://localhost:3001/health

# MCP endpoint: POST/GET/DELETE http://localhost:3001/mcp

マルチベース（セルフホスト）

単一のプロセスから複数のベースを提供します。

SEATABLE_SERVER_URL=https://your-seatable-server.com \
SEATABLE_BASES='[{"base_name":"CRM","api_token":"token_abc"},{"base_name":"Projects","api_token":"token_def"}]' \
npx -y @seatable/mcp-seatable

各ツールには base パラメーターが自動的に追加されます。利用可能なベースを確認するには、list_bases を使用します。

マネージドモード（マルチテナント HTTP）

各クライアントが独自の SeaTable API トークンで認証する MCP エンドポイントをホストする場合：

SEATABLE_MODE=managed \
SEATABLE_SERVER_URL=https://your-seatable-server.com \
SEATABLE_TOKEN_SECRET=$(openssl rand -hex 32) \
PORT=3000 npx -y @seatable/mcp-seatable --sse

マネージドモードでは、SEATABLE_TOKEN_SECRET が必須です。この値でサーバーが発行する OAuth トークンを保護するため、SeaTable API トークンそのものをクライアントに渡す必要はありません。再起動後も同じ値を維持してください。変更すると、発行済みのすべてのアクセストークンとリフレッシュトークンが無効になり、すべてのクライアントで再認証が必要になります。

クライアントは、セッションの初期化時と、その後のすべてのリクエスト（GET と DELETE を含む）で、Authorization: Bearer <token> を使って認証情報を渡します。mcp-session-id ヘッダーはルーティング値としてのみ使用され、それ単独で受け付けられることはありません。各リクエストは再検証され、セッションを作成したものと同じアイデンティティに解決される必要があります。そうでない場合、サーバーは 401（認証情報がない、または無効）または 403（認証情報は有効だが、セッションが異なる）を返します。レート制限は従来どおり適用されます（トークンごとに 60 リクエスト/分、IP ごとに 120 リクエスト/分、トークンごとに同時接続 20 件）。

OAuth サポート： マネージドモードでは OAuth 2.0 エンドポイント（/authorize と /token）も公開されるため、ChatGPT などの OAuth 対応クライアントが接続できます。外部の OAuth プロバイダーは不要です。このフローでは、ユーザーが SeaTable API トークンを入力します。サーバーはそのトークンを保護し、短期間有効なアクセストークン（1 時間）とローテーションするリフレッシュトークン（14 日）に変換します。SeaTable API トークンそのものがクライアントに返されることはありません。

クライアントは、最初に /register で登録する必要があります。返された client_id にはクライアント名と redirect_uris が紐づき、サーバーはクライアントが登録したコールバックのみを受け付けます（RFC 8252 に従い、ループバックコールバックではポートを変更できます）。PKCE の S256 は必須であり、すべての認可コードはクライアント、正確なコールバック、およびチャレンジに紐づけられます。

コードの送信先として許可される場所。 動的登録がオープンな場合、「登録済みクライアント」であることは信頼性の証明にはなりません。誰でも登録できるためです。重要なのは、コードがユーザーのマシンの外に送信されるかどうかです。

コールバック	動作
ループバック（http://127.0.0.1:…、localhost、[::1]）	許可されます。追加の手順は不要です。コードはユーザーのマシン内にとどまります
プライベート利用スキーム（cursor://、vscode://、com.example.app:/…）	許可されます。追加の手順は不要です。ローカルアプリケーションに渡されます
SEATABLE_OAUTH_TRUSTED_REDIRECT_HOSTS に含まれるホストの https	許可されます。追加の手順は不要です
その他のホストの https	ユーザーが別のページで送信先を確認した後に許可されます
リモートの平文 http、javascript:、data:、file:、blob:	拒否されます

確認はエントリーリンクから省略できません。確認情報はフォーム本文からのみ読み取られ、外部ページによる POST の自動送信は Sec-Fetch-Site によって拒否されます。そのため、信頼済みホストのリストは手間を省くためのものであり、アクセス制御ではありません。未設定でも問題はありません。

同意画面では、認可情報の送信先が最初に表示されます。オープン登録では、アプリケーション名は登録者が選択し、検証できないため、自己申告として表示されます。

OAuth エンドポイントには IP ごとのレート制限が適用されるため（全体で 30 リクエスト/分、トークン送信は 10 リクエスト/分）、/authorize を使って SeaTable API トークンを無制限にテストすることはできません。

OAuth エンドポイントは MCP 仕様（RFC 8414 のメタデータ探索、PKCE、動的クライアント登録）に準拠しています。

エンドポイント	パス
メタデータ探索	/.well-known/oauth-authorization-server
認可	/authorize
トークン	/token
クライアント登録	/register

クライアント ID とシークレットは検証されません。動的クライアント登録によって自動的に生成されます。

Docker

docker run -d --name seatable-mcp \
  -p 3000:3000 \
  -e SEATABLE_SERVER_URL=https://your-seatable-server.com \
  -e SEATABLE_API_TOKEN=your-api-token \
  seatable/seatable-mcp:latest

# Health check
curl http://localhost:3000/health

セキュリティモデル

トランスポートモードによって、セキュリティ特性は大きく異なります。

	stdio（デフォルト）	セルフホスト HTTP	マネージド HTTP
ネットワークへの公開	なし（ローカルプロセス）	TCP ポート、認証なし	TCP ポート、Bearer 認証
認証	不要（ローカル）	なし	SeaTable によって検証される Bearer トークンまたは OAuth 2.0
レート制限	なし	なし	トークンごと、IP ごと、グローバル
接続数の制限	該当なし	なし	トークンごとに同時セッション数 20
データの範囲	設定済みのすべてのベース	設定済みのすべてのベース	クライアントトークンごとに 1 つのベース

⚠️ 警告： セルフホスト HTTP モード（--sse／--http）には認証がありません。ポートに接続できる人は誰でも、書き込みや削除操作を含め、設定済みのすべてのベースに完全にアクセスできます。信頼できるネットワーク（localhost、Docker 内部）でのみ実行するか、認証を処理するリバースプロキシの背後で実行してください。信頼できないネットワークでは、代わりにマネージドモードを使用してください。

レート制限

SeaTable 独自の API ゲートウェイは、ベースごと（デフォルト：base_uuid ごとに毎分 500 リクエスト）および組織ごと（月間クォータ）にレート制限を適用します。これらの制限は、リクエストが MCP サーバー、Web UI、または直接 API 呼び出しのいずれから送信されたかにかかわらず適用されます。MCP サーバーはこれらの制限を重複して適用しません。代わりに、SeaTable が 429 Too Many Requests を返した場合に、指数バックオフを使って自動的に再試行します。

マネージドモードでは、MCP サーバー自身のプロセスを（SeaTable バックエンドではなく）保護するために、独自のレート制限を追加します。トークンごとに毎分 60 リクエスト、IP ごとに毎分 120 リクエスト、新規セッション作成は毎分 30 回、トークンごとの同時接続数は 20 です。

入力の検証

すべてのツール入力は、実行前に Zod スキーマで検証されます。書き込みツール（add_row、append_rows、update_rows、upsert_rows）ではさらに、テーブルスキーマに照らして行データを検証します。不明な列は拒否され、読み取り専用の列（数式、自動採番、作成者など）はレスポンスに注記を付けて除外されます。

ツールスキーマは、内部フィールド（例：_meta）を付与する場合がある MCP クライアントとの互換性を保つため、additionalProperties: true を指定して公開されます。予期しないフィールドはサーバーによって無視されます。エラーにはなりませんが、処理もされません。これは意図的なトレードオフです。より厳格な検証にすると、入力ミスに対するエラーメッセージは改善しますが、MCP クライアントとの互換性が損なわれるおそれがあります。

行のレスポンス

行のレスポンスには、すべての列と SeaTable のシステムフィールド（_id、_mtime、_ctime、_creator、_last_modifier）が含まれます。システムフィールドは除外されません。_id は更新と削除に必要で、タイムスタンプは並べ替えや最新状態の確認に役立ち、作成者／変更者フィールドは list_collaborators を使って表示名に解決できます。

キャッシュ

サーバーは、書き込み操作中の重複した API 呼び出しを避けるため、ベースのメタデータ（テーブル／列の定義）を 60 秒間キャッシュします。スキーマを読み取るツール（get_schema、list_tables）は常にキャッシュを迂回し、最新のデータを返します。キャッシュされたスキーマが古くなった場合（例：列名が変更された場合）、SeaTable API は書き込みを拒否します。その場合、AI エージェントは get_schema を呼び出してスキーマを更新できます。

環境変数

必須：

• SEATABLE_SERVER_URL — SeaTable サーバーの URL

認証（セルフホストモードでは、次のいずれかが必須です）：

• SEATABLE_API_TOKEN — 単一ベースの API トークン
• SEATABLE_BASES — マルチベース：JSON 配列（例：'[{"base_name":"CRM","api_token":"..."}]'）

任意：

• SEATABLE_MODE — selfhosted（デフォルト）または managed（クライアントごとの認証を使用するマルチテナント HTTP）
• SEATABLE_TOKEN_SECRET — managed モードでは必須。32 文字以上。発行された OAuth トークンとクライアント登録を封印します。再起動後も同じ値を使用する必要があります（openssl rand -hex 32）
• SEATABLE_ACCESS_TOKEN_TTL — 発行されたアクセストークンの有効期間（秒、デフォルトは 3600、範囲は 30～2592000）。値を小さくすると、SeaTable トークンが取り消された後の猶予期間が短くなります。値を大きくすると、クライアントの更新処理に問題があっても、ユーザーに再度プロンプトを求めずに済みます。リフレッシュトークンの有効期間がアクセストークンより短くなることはありません。
• SEATABLE_MOCK=true — オフラインテスト用のモックモードを有効にします
• CORS_ALLOWED_ORIGINS — CORS で許可するオリジンのカンマ区切りリスト（HTTP モードのみ。未設定の場合は無効）
• METRICS_PORT — Prometheus メトリクスのポート（デフォルト：9090、HTTP モードのみ）

モニタリング

HTTP モードでは、サーバーは別のポート（デフォルトは 9090）で Prometheus メトリクスを公開します。

curl http://localhost:9090/metrics

利用可能なメトリクス：

メトリクス	種類	説明
mcp_tool_calls_total{tool, status}	Counter	名前と結果（成功／エラー）別のツール呼び出し数
mcp_tool_calls_by_tool_total{tool}	Counter	ツールごとの呼び出し総数（結果を問わない）
mcp_tool_duration_seconds{tool}	Histogram	ツールの実行時間
mcp_http_requests_total{method, status}	Counter	メソッドとステータスコード別の HTTP リクエスト数
mcp_rate_limit_exceeded_total{type}	Counter	レート制限による拒否数（global／per_ip／per_token）
mcp_auth_validations_total{result}	Counter	認証検証数（success／failure／cache_hit）
mcp_active_sessions	Gauge	現在アクティブな HTTP セッション数
mcp_active_connections	Gauge	現在アクティブな接続数
seatable_api_requests_total{operation, status}	Counter	操作別の SeaTable API 呼び出し数
seatable_api_duration_seconds{operation}	Histogram	操作別の SeaTable API レイテンシ

さらに、prom-client を介して標準の Node.js メトリクス（メモリ、CPU、イベントループ）も利用できます。

メトリクスサーバーは HTTP モード（stdio ではありません）でのみ起動し、0.0.0.0 にバインドします。Docker では、ポートを内部ネットワーク内でのみ公開してください。

MCP ツール

スキーマの概要

• list_tables — メタデータ付きですべてのテーブルを取得します
• get_schema — データベースの完全な構造を取得します
• list_bases — 利用可能なベースを一覧表示します（マルチベースモードのみ）
• list_collaborators — ベースへのアクセス権を持つユーザーを一覧表示します（コラボレーター列用）

データの読み取り

• list_rows — ページネーション付きで行を一覧表示します（フィルタリングや並べ替えには query_sql を使用してください）
• get_row — ID を指定して特定の行を取得します
• find_rows — DSL を使用してクライアント側でフィルタリングします
• search_rows — SQL WHERE 句を使用して検索します
• query_sql — パラメーター化された入力で SQL クエリを実行します

データの書き込み

• add_row — 新しい行を 1 件追加します
• append_rows — 行を一括挿入します
• update_rows — 行を一括更新します
• upsert_rows — キー列を使用して行を挿入または更新します
• delete_rows — ID を指定して行を削除します

ファイル

• upload_file — ファイルまたは画像を Base64 エンコードして行にアップロードします
• download_file — ファイル列または画像列からファイルの内容を読み取ります（テキストファイルと PDF はテキストとして、バイナリファイルはダウンロードリンクとして取得します。最大 1 MB）

リンク

• link_rows — 行同士のリレーションシップを作成します
• unlink_rows — リレーションシップを削除します

ユーティリティ

• get_row_activities — 行の変更履歴を取得します（誰が、いつ、何を変更したか、変更前後の値）
• create_snapshot — 現在のベースのスナップショットを作成します（クールダウンは10分です）
• add_select_options — 単一選択または複数選択列に新しいオプションを追加します（既存のオプションはスキップされ、重複しません）
• ping_seatable — レイテンシーを監視するヘルスチェック

対応する列タイプ

SeaTable のベースには、さまざまな列タイプを含めることができます。次の表では、API 経由で書き込み可能なタイプと、使用する形式を示します。

列タイプ	書き込み可能	値の形式
テキスト	はい	"string"
長文テキスト	はい	"Markdown string"
数値（パーセント、通貨を含む）	はい	123.45
チェックボックス	はい	true / false
日付	はい	"YYYY-MM-DD" または "YYYY-MM-DD HH:mm"
期間	はい	"h:mm" または "h:mm:ss"
単一選択	はい	"option name"
複数選択	はい	["option a", "option b"]
メールアドレス	はい	"[email protected]"
URL	はい	"https://..."
評価	はい	4（整数）
位置情報	はい	{"lat": 52.52, "lng": 13.40}
コラボレーター	はい	["[email protected]"] — ユーザー ID の取得には list_collaborators を使用します
リンク	はい	link_rows / unlink_rows ツールを使用します
画像／ファイル	はい	アップロードには upload_file（base64）を、内容の読み取りには download_file を使用します
数式／リンク数式	いいえ	読み取り専用で、SeaTable によって計算されます
作成者／作成日時／更新日時	いいえ	読み取り専用で、自動的に設定されます
自動採番	いいえ	読み取り専用で、自動的に設定されます
ボタン／デジタル署名	いいえ	API 経由ではアクセスできません

ツールの例

// List all tables
{ "tool": "list_tables", "args": {} }

// Get rows with pagination
{ "tool": "list_rows", "args": { "table": "Tasks", "page_size": 10 } }

// Add rows
{ "tool": "append_rows", "args": { "table": "Tasks", "rows": [{ "Title": "New Task", "Status": "Todo" }] } }

// SQL query
{ "tool": "query_sql", "args": { "sql": "SELECT Status, COUNT(*) as count FROM Tasks GROUP BY Status" } }

プログラムからの使用

import { createMcpServer } from '@seatable/mcp-seatable'

const server = await createMcpServer({
  serverUrl: 'https://your-seatable-server.com',
  apiToken: 'your-api-token',
})

モックモード

SEATABLE_MOCK=true npm run dev

SeaTable の実環境を使わずにデモやテストを行うための、メモリ内のテーブルと行です。

開発

前提条件

• Node.js >= 20

セットアップ

git clone https://github.com/seatable/seatable-mcp
cd seatable-mcp
npm install
cp .env.example .env   # Configure your SeaTable settings
npm run dev             # Start in watch mode

スクリプト

• npm run dev — ウォッチモード（tsx）でサーバーを起動します
• npm run build — TypeScript をコンパイルします
• npm run start — コンパイル済みのサーバーを実行します
• npm test — テストを実行します（vitest）
• npm run lint — コードをリントします
• npm run typecheck — TypeScript の型チェックを実行します

テストツール

node scripts/mcp-call.cjs ping_seatable '{}'
node scripts/mcp-call.cjs list_tables '{}'
node scripts/mcp-call.cjs list_rows '{"table": "Tasks", "page_size": 5}'

トラブルシューティング

問題	解決策
Invalid API token	SEATABLE_API_TOKEN を確認してください
Base not found	API トークンの権限を確認してください
Connection timeout	SEATABLE_SERVER_URL とネットワークアクセスを確認してください
Permission denied	API トークンに必要なベースの権限があることを確認してください
You don't have permission to perform this operation on this base.	API トークンが読み取り専用であるか、行数の上限を超えています
Asset quota exceeded.	ストレージの容量上限に達しました。ファイルを削除するか、プランをアップグレードしてください
too many requests	SeaTable によってリクエストがレート制限されています。リクエストはバックオフ付きで自動的に再試行されます（3回）

ライセンス

MIT