AI导哈

Grist文档交互服务

grist-mcp是一个MCP服务器，允许AI代理读写和修改Grist电子表格，提供基于令牌的安全访问控制和细粒度的文档权限管理。

  • by Xe138
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Xe138/grist-mcp-server

使用说明

grist mcp

MCP服务器，用于AI代理与Grist文档交互。

概述

grist mcp是一个 模型上下文协议（MCP） 服务器，使AI代理能够读取、写入和修改Grist电子表格。它提供安全的、基于令牌的访问控制，每个文档都有精细的权限。

特性

  • 发现：列出具有权限的可访问文档
  • 读取操作：列出表、描述列、获取记录、运行SQL查询
  • 写入操作：添加、更新和删除记录
  • 架构操作：创建表，添加/修改/删除列
  • 安全：基于令牌的身份验证，具有每个文档的权限范围（读取、写入、架构）
  • 多用户：支持多个Grist实例和文档

快速入门（Docker）

先决条件

  • Docker和Docker Compose
  • 使用API密钥访问一个或多个Grist文档

1.创建配置目录

mkdir grist-mcp && cd grist-mcp

2.下载配置文件

# Download docker-compose.yml
curl -O https://raw.githubusercontent.com/Xe138/grist-mcp-server/master/deploy/prod/docker-compose.yml

# Download example config
curl -O https://raw.githubusercontent.com/Xe138/grist-mcp-server/master/config.yaml.example
cp config.yaml.example config.yaml

3.生成代币

为您的代理生成安全令牌：

python -c "import secrets; print(secrets.token_urlsafe(32))"
# or
openssl rand -base64 32

4.配置config.yaml

编辑 config.yaml 定义您的Grist文档和代理令牌：

# Document definitions
documents:
  my-document:                           # Friendly name (used in token scopes)
    url: https://docs.getgrist.com       # Your Grist instance URL
    doc_id: abcd1234efgh5678             # Document ID from the URL
    api_key: your-grist-api-key          # Grist API key (or use ${ENV_VAR} syntax)

# Agent tokens with access scopes
tokens:
  - token: your-generated-token-here     # The token you generated in step 3
    name: my-agent                       # Human-readable name
    scope:
      - document: my-document            # Must match a document name above
        permissions: [read, write]       # Allowed: read, write, schema

查找您的Grist文档ID：在浏览器中打开Grist文档。URL看起来像： https://docs.getgrist.com/abcd1234efgh5678/My-Document -文档ID为 abcd1234efgh5678.

获取Grist API密钥：在Grist中，转到配置文件设置→ API → 创建API密钥。

5.创建.env文件

创建一个 .env 使用您的代理令牌的文件：

# .env
GRIST_MCP_TOKEN=your-generated-token-here
PORT=3000

这 GRIST_MCP_TOKEN 必须与中定义的令牌之一匹配 config.yaml.

6.启动服务器

docker compose up -d

服务器将在以下时间可用 http://localhost:3000.

7.配置您的MCP客户端

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "grist": {
      "type": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}

可用工具

发现

工具 说明
list_documents 列出此代理及其权限可访问的文档

读取操作（需要 read 许可）

工具 说明
list_tables 列出文档中的所有表
describe_table 获取表的列信息（id、类型、公式）
get_records 使用可选的筛选器、排序和限制获取记录
sql_query 对文档运行只读SELECT查询

写入操作（需要 write 许可）

工具 说明
add_records 向表中添加新记录
update_records 按ID更新现有记录
delete_records 按ID删除记录

架构操作（必需 schema 许可）

工具 说明
create_table 创建具有指定列的新表
add_column 向现有表添加列
modify_column 更改列的类型或公式
delete_column 从表中删除列

配置参考

环境变量

变量 描述 默认值
PORT 服务器端口 3000
GRIST_MCP_TOKEN 代理身份验证令牌（必需） -
CONFIG_PATH 容器内配置文件的路径 /app/config.yaml
LOG_LEVEL 记录冗长(DEBUG, INFO, WARNING, ERROR) INFO
GRIST_MCP_URL 此服务器的公共URL（用于会话代理令牌） -

config.yaml结构

# Document definitions (each is self-contained)
documents:
  budget-2024:
    url: https://work.getgrist.com
    doc_id: mK7xB2pQ9mN4v
    api_key: ${GRIST_WORK_API_KEY}      # Supports environment variable substitution

  personal-tracker:
    url: https://docs.getgrist.com
    doc_id: pN0zE5sT2qP7x
    api_key: ${GRIST_PERSONAL_API_KEY}

# Agent tokens with access scopes
tokens:
  - token: your-secure-token-here
    name: finance-agent
    scope:
      - document: budget-2024
        permissions: [read, write]       # Can read and write

  - token: another-token-here
    name: readonly-agent
    scope:
      - document: budget-2024
        permissions: [read]              # Read only
      - document: personal-tracker
        permissions: [read, write, schema]  # Full access

权限级别

  • read：查询表和记录，运行SQL查询
  • write：添加、更新、删除记录
  • schema：创建表，添加/修改/删除列

日志记录

配置

设置 LOG_LEVEL 用于控制日志详细程度的环境变量：

级别 描述
DEBUG 显示所有日志，包括HTTP请求和工具参数
INFO 显示带有统计信息的工具调用（默认）
WARNING 仅显示身份验证错误和警告
ERROR 仅显示错误 
# In .env or docker-compose.yml
LOG_LEVEL=INFO

日志格式

在 INFO 级别，每次工具调用都会生成一条日志行：

2026-01-02 10:15:23 | agent-name (abc...xyz) | get_records | sales | 42 records | success | 125ms
字段 描述
时间戳 YYYY-MM-DD HH:MM:SS
代理 带有截断令牌的代理名称
工具 MCP工具名称
文档 文档名称（或 - 对于list_documents）
统计 操作结果（例如。， 42 records, 3 tables)
状态 success, auth_error，或 error
持续时间 执行时间（毫秒）

错误包括第二行缩进的详细信息：

2026-01-02 10:15:23 | agent-name (abc...xyz) | add_records | sales | - | error | 89ms
    Grist API error: Invalid column 'foo'

生产建议

  • 使用 LOG_LEVEL=INFO 正常运行（默认）
  • 使用 LOG_LEVEL=DEBUG 用于故障排除（显示HTTP流量）
  • 使用 LOG_LEVEL=WARNING 用于最小化日志记录

安全

  • 基于令牌的身份验证：每个代理都有一个具有特定文档访问权限的唯一令牌
  • 权限范围：粒度控制 read, write，以及 schema 权限
  • SQL验证：只允许SELECT查询，不允许多语句查询
  • API密钥隔离：每个文档都可以使用不同的Grist API密钥
  • 无代币风险：令牌在启动时验证，不存储在响应中

发展

需求

  • Python 3.14+
  • uv包管理器

本地设置

# Clone the repository
git clone https://github.com/Xe138/grist-mcp-server.git
cd grist-mcp-server

# Install dependencies
uv sync --dev

# Run tests
make test-unit

本地运行

export GRIST_MCP_TOKEN="your-agent-token"
CONFIG_PATH=./config.yaml uv run python -m grist_mcp.main

项目结构

grist-mcp/
├── src/grist_mcp/
│   ├── main.py          # Entry point
│   ├── server.py        # MCP server setup and tool registration
│   ├── config.py        # Configuration loading
│   ├── auth.py          # Authentication and authorization
│   ├── grist_client.py  # Grist API client
│   └── tools/
│       ├── discovery.py # list_documents
│       ├── read.py      # Read operations
│       ├── write.py     # Write operations
│       └── schema.py    # Schema operations
├── tests/
│   ├── unit/            # Unit tests
│   └── integration/     # Integration tests
├── deploy/
│   ├── dev/             # Development docker-compose
│   ├── test/            # Test docker-compose
│   └── prod/            # Production docker-compose
└── config.yaml.example

许可证

麻省理工学院

相关 MCP