Grist MCP Server

Grist MCP サーバー

Grist API と連携するための MCP（Model Context Protocol）サーバーです。このサーバーを使うと、Claude などの言語モデルから直接 Grist のデータにアクセスして操作できます。

プロジェクトの構成

mcp-server-grist/
├── src/
│   └── mcp_server_grist/     # Package principal
│       ├── __init__.py       # Point d'entrée du package
│       ├── __main__.py       # Support pour exécution en module
│       ├── version.py        # Gestion de version
│       ├── main.py           # Point d'entrée principal
│       ├── server.py         # Configuration du serveur MCP
│       ├── client.py         # Client API Grist
│       ├── tools/            # Outils MCP organisés par catégorie
│       └── models.py         # Modèles de données Pydantic
├── tests/                    # Tests unitaires et d'intégration
├── docs/                     # Documentation détaillée
├── requirements.txt          # Dépendances Python
├── pyproject.toml           # Configuration moderne du package
├── Dockerfile               # Configuration Docker
├── docker-compose.yml       # Configuration multi-services
├── .env.template            # Template pour variables d'environnement
└── README.md                # Documentation principale

前提条件

• Python 3.8+
• 有効な Grist API キー
• 次の Python パッケージ：fastmcp、httpx、pydantic、python-dotenv

その場での使用

uvx を使用（推奨）

uvx を使用すると、実行時に環境の構築とパッケージのダウンロードが行われます。

uvx mcp-server-grist

MCP プロトコルに対応したお好みの AI アシスタントでの使用

JSON 設定は次のとおりです。

{
    "mcpServers": {
        "grist-server": {
            "disabled": false,
            "timeout": 60,
            "type": "stdio",
            "command": "uvx",
            "args": [
                "mcp-server-grist"
            ],
            "env": {
                "GRIST_API_KEY": "ta_cle_API_GRIST"
            }
        }
    }
}

インストール

pip を使用

pip install mcp-server-grist

インストール後、次のコマンドでサーバーを実行できます。

mcp-server-grist

Claude Desktop での使用

この MCP サーバーを Claude Desktop で使用するには、mcp_servers.json ファイルに次の設定を追加してください。

{
  "mcpServers": {
    "grist-mcp": {
      "command": "node",
      "args": [
        "chemin/vers/npm-wrapper/bin/start.js"
      ],
      "env": {
        "GRIST_API_KEY": "votre_clé_api_grist",
        "GRIST_API_URL": "https://docs.getgrist.com/api"
      }
    }
  }
}

chemin/vers/npm-wrapper/bin/start.js を、このパッケージに含まれる Node.js ラッパーの start.js スクリプトへの絶対パスに置き換えてください。

開発モードでのインストール

サーバーへの貢献やカスタマイズを行う場合：

# Cloner le repository
git clone https://github.com/modelcontextprotocol/mcp-server-grist.git
cd mcp-server-grist

# Installer en mode développement
pip install -e .

# Lancer les tests
python -m pytest tests

Docker を使用

Docker ですばやくデプロイするには：

# Construire l'image
docker build -t mcp/grist-mcp-server .

# Exécuter le container
docker run -it --rm \
  -e GRIST_API_KEY=votre_clé_api \
  -e GRIST_API_HOST=https://docs.getgrist.com/api \
  mcp/grist-mcp-server

Docker Compose を使用

複数のトランスポートモードを並行してデプロイするには：

# Configurer les variables d'environnement
cp .env.example .env
# Éditer le fichier .env avec votre clé API

# Lancer les services
docker-compose up

設定

環境変数

.env.template をもとに .env ファイルを作成し、次の変数を設定してください。

GRIST_API_KEY=votre_clé_api
GRIST_API_HOST=https://docs.getgrist.com/api
LOG_LEVEL=INFO  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

API キーは Grist アカウントの設定で確認できます。

Claude Desktop での設定

claude_desktop_config.json に次の設定を追加してください。

Python 版

{
  "mcpServers": {
    "grist-mcp": {
      "command": "python",
      "args": [
        "-m", "grist_mcp_server"
      ]
    }
  }
}

Docker 版

{
  "mcpServers": {
    "grist-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "GRIST_API_KEY=votre_clé_api",
        "-e", "GRIST_API_HOST=https://docs.getgrist.com/api",
        "mcp/grist-mcp-server"
      ]
    }
  }
}

起動オプション

このサーバーは、MCP 標準に準拠した複数のトランスポートモードに対応しています。

モジュールモード（推奨）

# Mode stdio (par défaut pour Claude)
python -m mcp_server_grist --transport stdio

# Mode HTTP streamable (pour intégration web)
python -m mcp_server_grist --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

# Active le mode debug avec logging détaillé
python -m mcp_server_grist --debug

追加オプション

Options:
  --transport {stdio,streamable-http,sse}
                        Type de transport à utiliser
  --host HOST           Hôte pour les transports HTTP (défaut: 127.0.0.1)
  --port PORT           Port pour les transports HTTP (défaut: 8000)
  --path PATH           Chemin pour streamable-http (défaut: /mcp)
  --mount-path MOUNT_PATH
                        Chemin pour SSE (défaut: /sse)
  --debug               Active le mode debug
  --help                Affiche l'aide

トランスポートのセキュリティ

HTTP トランスポートでは、次の設定を推奨します。

• ネットワークからのアクセスをローカルに限定するため、0.0.0.0 ではなく 127.0.0.1（localhost）を使用する
• DNS リバインディング攻撃を防ぐため、オリジン検証（validate_origin）を有効にする
• インターネットに公開する場合は、HTTPS 対応のリバースプロキシを使用する

機能

• 言語モデルから Grist のデータに直接アクセス
• 組織、ワークスペース、ドキュメント、テーブル、列の一覧表示
• レコードの管理（作成、読み取り、更新、削除）
• 高度なクエリ機能によるデータのフィルタリングと並べ替え
• SQL クエリに対応（SELECT のみ）
• API キーによる安全な認証
• ユーザーアクセスの管理
• エクスポートとダウンロード（SQLite、Excel、CSV）
• 添付ファイルの管理
• Webhook の管理
• 数式のインテリジェントな検証

利用可能なツール

組織とドキュメントの管理

• list_organizations ：組織の一覧を取得します
• describe_organization ：組織の詳細情報を取得します
• modify_organization ：組織を変更します
• delete_organization ：組織を削除します
• list_workspaces ：組織内のワークスペースの一覧を取得します
• describe_workspace ：ワークスペースの詳細情報を取得します
• create_workspace ：新しいワークスペースを作成します
• modify_workspace ：ワークスペースを変更します
• delete_workspace ：ワークスペースを削除します
• list_documents ：ワークスペース内のドキュメントの一覧を取得します
• describe_document ：ドキュメントの詳細情報を取得します
• create_document ：新しいドキュメントを作成します
• modify_document ：ドキュメントを変更します
• delete_document ：ドキュメントを削除します
• move_document ：ドキュメントを別のワークスペースに移動します
• force_reload_document ：ドキュメントを強制的に再読み込みします
• delete_document_history ：ドキュメントの履歴を削除します

テーブルと列の管理

• list_tables ：ドキュメント内のテーブルの一覧を取得します
• create_table ：新しいテーブルを作成します
• modify_table ：テーブルを変更します
• list_columns ：テーブル内の列の一覧を取得します
• create_column ：新しい列を作成します
• create_column_with_feedback ：検証と詳細なフィードバック付きで列を作成します
• modify_column ：列を変更します
• delete_column ：列を削除します
• create_column_with_formula_safe ：検証付きで数式列を作成します
• get_formula_helpers ：数式の作成に役立つ情報を取得します
• validate_formula ：数式を検証し、修正案を提示します
• get_table_schema ：テーブルのスキーマを取得します

データ操作

• list_records ：並べ替えと件数制限を指定してレコードの一覧を取得します
• add_grist_records ：レコードを追加します
• add_grist_records_safe ：検証付きでレコードを追加します
• update_grist_records ：レコードを更新します
• delete_grist_records ：レコードを削除します

フィルタリングと SQL クエリ

• filter_sql_query ：単純なフィルタリング向けに最適化された SQL クエリ
  • よく使われるフィルター向けの簡易インターフェース
  • 並べ替えと件数制限に対応
  • 基本的な WHERE 条件
• execute_sql_query ：複雑な SQL クエリ
  • カスタム SQL クエリ
  • JOIN とサブクエリに対応
  • パラメーターとタイムアウトを設定可能

アクセス管理

• list_organization_access ：組織にアクセスできるユーザーの一覧を取得します
• modify_organization_access ：ユーザーの組織へのアクセス権を変更します
• list_workspace_access ：ワークスペースにアクセスできるユーザーの一覧を取得します
• modify_workspace_access ：ユーザーのワークスペースへのアクセス権を変更します
• list_document_access ：ドキュメントにアクセスできるユーザーの一覧を取得します
• modify_document_access ：ユーザーのドキュメントへのアクセス権を変更します

エクスポートとダウンロード

• download_document_sqlite ：ドキュメントを SQLite 形式でダウンロードします
• download_document_excel ：ドキュメントを Excel 形式でダウンロードします
• download_table_csv ：テーブルを CSV 形式でダウンロードします

添付ファイルの管理

• list_attachments ：ドキュメント内の添付ファイルの一覧を取得します
• get_attachment_info ：添付ファイルの情報を取得します
• download_attachment ：添付ファイルをダウンロードします
• upload_attachment ：添付ファイルをアップロードします

Webhook の管理

• list_webhooks ：ドキュメントの Webhook の一覧を取得します
• create_webhook ：Webhook を作成します
• modify_webhook ：Webhook を変更します
• delete_webhook ：Webhook を削除します
• clear_webhook_queue ：Webhook のキューを空にします

使用例

# Liste des organisations
orgs = await list_organizations()

# Liste des espaces de travail
workspaces = await list_workspaces(org_id=1)

# Liste des documents
docs = await list_documents(workspace_id=1)

# Liste des tables
tables = await list_tables(doc_id="abc123")

# Liste des colonnes
columns = await list_columns(doc_id="abc123", table_id="Table1")

# Liste des enregistrements avec tri et limite
records = await list_records(
    doc_id="abc123",
    table_id="Table1",
    sort="name",
    limit=10
)

# Filtrage simple avec filter_sql_query
filtered_records = await filter_sql_query(
    doc_id="abc123",
    table_id="Table1",
    columns=["name", "age", "status"],
    where_conditions={
        "organisation": "OPSIA",
        "status": "actif"
    },
    order_by="name",
    limit=10
)

# Requête SQL complexe avec execute_sql_query
sql_result = await execute_sql_query(
    doc_id="abc123",
    sql_query="""
        SELECT t1.name, t1.age, t2.department
        FROM Table1 t1
        JOIN Table2 t2 ON t1.id = t2.employee_id
        WHERE t1.status = ? AND t1.age > ?
        ORDER BY t1.name
        LIMIT ?
    """,
    parameters=["actif", 25, 10],
    timeout_ms=2000
)

# Ajout d'enregistrements
new_records = await add_grist_records(
    doc_id="abc123",
    table_id="Table1",
    records=[{"name": "John", "age": 30}]
)

# Mise à jour d'enregistrements
updated_records = await update_grist_records(
    doc_id="abc123",
    table_id="Table1",
    records=[{"id": 1, "name": "John", "age": 31}]
)

# Création d'une colonne de formule avec validation
formula_column = await create_column_with_formula_safe(
    doc_id="abc123",
    table_id="Table1",
    column_label="Total",
    formula="$Prix * $Quantité",
    column_type="Numeric"
)

# Téléchargement d'un document au format Excel
excel_doc = await download_document_excel(
    doc_id="abc123",
    header_format="label"
)

# Gestion des accès
await modify_document_access(
    doc_id="abc123",
    user_email="[email protected]",
    access_level="editors"
)

詳細なユースケース

ナビゲーションと探索

• list_organizations, list_workspaces, list_documents, list_tables, list_columns
  • Grist の構造を調べ、利用可能なデータを確認するために使用します
  • 特定の操作を実行する前に ID を取得する必要があります
  • データ分析の初期段階に最適です

クエリとフィルタリング

• list_records：テーブル内のすべてのレコードを取得します
• filter_sql_query：単一テーブルのシンプルなフィルタリングに使用します
• execute_sql_query：結合やサブクエリを含む複雑なクエリに使用します

データ操作

• add_grist_records と add_grist_records_safe：検証の有無を指定してデータを追加します
• update_grist_records：既存のレコードを変更します
• delete_grist_records：レコードを削除します

数式の操作

• get_formula_helpers：列参照の正しい構文を取得します
• validate_formula：数式を検証し、自動的に修正します
• create_column_with_formula_safe：安全な計算列を作成します

エクスポートとダウンロード

• download_document_sqlite、download_document_excel、download_table_csv：データをエクスポートします
• download_attachment：添付ファイルを取得します

アクセス管理

• list_*_access と modify_*_access：ユーザー権限を管理します

外部連携

• create_webhook、modify_webhook：Grist を他のサービスに接続します

ユースケース

Grist MCP サーバーは、次の用途向けに設計されています：

• Grist のデータを分析し、要約する
• プログラムからレコードを作成、更新、削除する
• レポートとビジュアライゼーションを作成する
• 保存されているデータに関する質問に回答する
• Grist を言語モデルに接続し、自然言語でクエリを実行する
• Grist のデータに関わるワークフローを自動化する
• Webhook を介して Grist を他のシステムと連携する

貢献

貢献を歓迎します！貢献する方法は次のとおりです：

1. プロジェクトをフォークします
2. 機能用のブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. Pull Request を作成します

ライセンス

この MCP サーバーは MIT ライセンスの下で公開されています。