grist-mcp-server

Grist MCP サーバー

Grist 用の MCP サーバーです。ドキュメント、レコード、SQL、ページを操作する 11 個のツールを備えています。

クイックスタート

Claude Code（推奨）

claude mcp add grist --env GRIST_API_KEY=your_api_key --env GRIST_BASE_URL=https://docs.getgrist.com -- npx -y grist-mcp-server

Claude Desktop（MCPB バンドル）

1. Releases から grist-mcp-server.mcpb をダウンロードします
2. Claude Desktop で「Settings」→「Developer」→「MCP Servers」→「Install from MCPB」の順に選択します
3. Grist API キーとベース URL を設定します
4. Claude Desktop を再起動します

手動設定（.mcp.json）

.mcp.json ファイルに追加します。

{
  "mcpServers": {
    "grist": {
      "command": "npx",
      "args": ["-y", "grist-mcp-server"],
      "env": {
        "GRIST_API_KEY": "your_api_key",
        "GRIST_BASE_URL": "https://docs.getgrist.com"
      }
    }
  }
}

ソースからインストール

git clone https://github.com/gwhthompson/grist-mcp-server.git
cd grist-mcp-server
npm install && npm run build

MCP 設定に追加します。

{
  "mcpServers": {
    "grist": {
      "command": "node",
      "args": ["/path/to/grist-mcp-server/dist/index.js"],
      "env": {
        "GRIST_API_KEY": "your_api_key",
        "GRIST_BASE_URL": "https://docs.getgrist.com"
      }
    }
  }
}

Cloudflare Workers（HTTP トランスポート）

Cloudflare Workers を使用して、HTTP ベースでアクセスできるリモート MCP サーバーとしてデプロイします。

ローカル開発：

npm run worker:dev

Cloudflare へのデプロイ：

npm run worker:deploy

設定：

Workers のデプロイでは、ヘッダーによる認証を使用します。

• X-Grist-API-Key：Grist API キー（必須）
• X-Grist-Base-URL：Grist インスタンスの URL（任意。デフォルトは https://docs.getgrist.com）

エンドポイント： https://your-worker.workers.dev/mcp

リクエスト例：

curl -X POST https://your-worker.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -H "X-Grist-API-Key: your_api_key" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

注意：

• ステートレス設計：リクエストごとに新しいサーバーインスタンスを作成します
• すべてのオリジンで CORS を有効にしています（Cookie ではなくヘッダーで認証するため安全です）
• wrangler secret put GRIST_API_KEY を使用して環境変数を設定します

ツール

ツール	用途
grist_get_workspaces	ワークスペースの一覧表示と絞り込み
grist_get_documents	ID、名前、またはワークスペースでドキュメントを検索
grist_get_tables	テーブル構造とスキーマを取得
grist_query_sql	JOIN と集計を含む SQL クエリを実行
grist_get_records	フィルターを指定してレコードを取得
grist_manage_records	レコードのすべての CRUD 操作（追加／更新／削除／アップサート）
grist_manage_schema	テーブル、列、集計のスキーマ操作
grist_manage_pages	ページのレイアウトと管理
grist_create_document	新しい Grist ドキュメントを作成、または既存のドキュメントをコピー
grist_manage_webhooks	リアルタイムのイベント通知用に Webhook を作成・管理
grist_help	ツールを確認し、JSON スキーマ付きの詳細なドキュメントを取得

例

データベースを作成する

1. grist_get_workspaces → find workspace
2. grist_create_document → create document
3. grist_manage_schema → create tables with columns

データをインポートする

1. grist_get_documents → find document
2. grist_get_tables → check structure
3. grist_manage_records → upsert data (adds new, updates existing)

データをクエリする

1. grist_get_tables → understand schema
2. grist_query_sql → run SQL with JOINs and aggregations

トラブルシューティング

サーバーが起動しない場合： 設定で GRIST_API_KEY が指定されていることを確認してください。

認証に失敗する場合： https://docs.getgrist.com/settings/keys で API キーを確認してください。

ドキュメント一覧が空の場合： GRIST_BASE_URL が Grist インスタンスと一致していることを確認してください。

接続エラー（セルフホストの場合）： URL に https:// が含まれていること、サーバーに接続できることを確認してください。

テスト

npm test  # Docker required - container lifecycle is automatic

ドキュメント

ツールの説明は簡潔です。詳細については grist_help を使用してください。

• grist_help({tools: ["grist_manage_records"], only: ["examples"]})
• grist_help({tools: ["grist_query_sql"], only: ["errors"]})

バージョン履歴については CHANGELOG.md をご覧ください。

リンク

• Grist ドキュメント
• Grist コミュニティ
• MCP プロトコル
• 問題を報告