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 wrapper 的 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

你可以在 Grist 账户设置中找到 API 密钥。

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 传输，我们建议：

• 使用 127.0.0.1（localhost），而非 0.0.0.0，以限制对本地网络的访问
• 启用来源验证（validate_origin），以防止 DNS 重绑定攻击
• 如需向互联网开放服务，请使用带 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. Fork 项目
2. 为你的功能创建分支
3. 提交更改
4. 推送到分支
5. 发起 Pull Request

许可证

此 MCP 服务采用 MIT 许可证。