麦普服务器-数据源

Name: 麦普服务器-数据源
Author: nic01asFr

作者：nic01asFr29 星标更新：2025-11-05

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Grist MCP Server

一个用于与Grist API交互的MCP（模型上下文协议）服务器。此服务器允许直接从语言模型如Claude访问和操作Grist数据。

项目结构

mcp-server-grist/
├── src/
│   └── mcp_server_grist/     # 主包
│       ├── __init__.py       # 包入口点
│       ├── __main__.py       # 模块执行支持
│       ├── version.py        # 版本管理
│       ├── main.py           # 主入口点
│       ├── server.py         # MCP服务器配置
│       ├── client.py         # Grist API客户端
│       ├── tools/            # 分类组织的MCP工具
│       └── models.py         # Pydantic数据模型
├── tests/                    # 单元测试和集成测试
├── docs/                     # 详细文档
├── requirements.txt          # Python依赖项
├── pyproject.toml           # 现代包配置
├── Dockerfile               # Docker配置
├── docker-compose.yml       # 多服务配置
├── .env.template            # 环境变量模板
└── README.md                # 主要文档

预备条件

Python 3.8+
有效的Grist API密钥
下列Python包：fastmcp, httpx, pydantic, python-dotenv

安装

通过pip安装（推荐）

pip install mcp-server-grist

安装后，可以通过以下命令运行服务器：

mcp-server-grist

与Claude Desktop一起使用

要将此MCP服务器与Claude Desktop一起使用，请在您的mcp_servers.json文件中添加以下配置：

{
  "mcpServers": {
    "grist-mcp": {
      "command": "node",
      "args": [
        "路径/到/npm-wrapper/bin/start.js"
      ],
      "env": {
        "GRIST_API_KEY": "您的grist_api_key",
        "GRIST_API_URL": "https://docs.getgrist.com/api"
      }
    }
  }
}

请将路径/到/npm-wrapper/bin/start.js替换为此包中包含的Node.js包装器脚本start.js的绝对路径。

开发模式安装

为了贡献或自定义服务器：

# 克隆仓库
git clone https://github.com/modelcontextprotocol/mcp-server-grist.git
cd mcp-server-grist

# 开发模式安装
pip install -e .

# 运行测试
python -m pytest tests

使用Docker

快速部署Docker：

# 构建镜像
docker build -t mcp/grist-mcp-server .

# 运行容器
docker run -it --rm \
  -e GRIST_API_KEY=您的api_key \
  -e GRIST_API_HOST=https://docs.getgrist.com/api \
  mcp/grist-mcp-server

使用Docker Compose

并行部署多个服务：

# 配置环境变量
cp .env.example .env
# 编辑.env文件以包含您的API密钥

# 启动服务
docker-compose up

配置

环境变量

基于.env.template创建一个.env文件，并包含以下变量：

GRIST_API_KEY=您的api_key
GRIST_API_HOST=https://docs.getgrist.com/api
LOG_LEVEL=INFO  # 可选项：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=您的api_key",
        "-e", "GRIST_API_HOST=https://docs.getgrist.com/api",
        "mcp/grist-mcp-server"
      ]
    }
  }
}

启动选项

该服务器支持多种符合MCP标准的传输方式：

模块模式（推荐）

# 标准IO模式（默认用于Claude）
python -m mcp_server_grist --transport stdio

# 可流式HTTP模式（用于Web集成）
python -m mcp_server_grist --transport streamable-http --host 127.0.0.1 --port  8000 --path /mcp

# Server-Sent Events模式（根据MCP 2025-03-26已弃用）
python -m mcp_server_grist --transport sse --host 127.0.0.1 --port 8000 --mount-path /sse

# 启用调试模式，带有详细的日志记录
python -m mcp_server_grist --debug

其他选项

选项:
  --transport {stdio,streamable-http,sse}
                        要使用的传输类型
  --host HOST           HTTP传输的主机（默认：127.0.0.1）
  --port PORT           HTTP传输的端口（默认：8000）
  --path PATH           streamable-http的路径（默认：/mcp）
  --mount-path MOUNT_PATH
                        SSE的路径（默认：/sse）
  --debug               启用调试模式
  --help                显示帮助信息

传输安全

对于HTTP和SSE传输，我们建议：

使用127.0.0.1（本地主机）而不是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队列

使用示例

# 列出组织
orgs = await list_organizations()

# 列出工作空间
workspaces = await list_workspaces(org_id=1)

# 列出文档
docs = await list_documents(workspace_id=1)

# 列出表
tables = await list_tables(doc_id="abc123")

# 列出列
columns = await list_columns(doc_id="abc123", table_id="Table1")

# 列出记录，带排序和限制
records = await list_records(
    doc_id="abc123",
    table_id="Table1",
    sort="name",
    limit=10
)

# 使用filter_sql_query进行简单过滤
filtered_records = await filter_sql_query(
    doc_id="abc123",
    table_id="Table1",
    columns=["name", "age", "status"],
    where_conditions={
        "organisation": "OPSIA",
        "status": "active"
    },
    order_by="name",
    limit=1
)

# 使用execute_sql_query进行复杂SQL查询
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=["active", 25, 10],
    timeout_ms=2000
)

# 添加记录
new_records = await add_grist_records(
    doc_id="abc123",
    table_id="Table1",
    records=[{"name": "John", "age": 30}]
)

# 更新记录
updated_records = await update_grist_records(
    doc_id="abc123",
    table_id="Table1",
    records=[{"id": 1, "name": "John", "age": 31}]
)

# 创建带有验证的公式列
formula_column = await create_column_with_formula_safe(
    doc_id="abc123",
    table_id="Table1",
    column_label="Total",
    formula="$Price * $Quantity",
    column_type="Numeric"
)

# 将文档下载为Excel格式
excel_doc = await download_document_excel(
    doc_id="abc123",
    header_format="label"
)

# 管理访问权限
await modify_document_access(
    doc_id="abc123",
    user_email="user@example.com",
    access_level="editors"
)

详细用例

导航和探索

list_organizations, list_workspaces, list_documents, list_tables, list_columns
- 用于探索Grist结构并发现可用数据
- 获取ID以便执行特定操作
- 适合数据分析的初始阶段

查询和过滤

list_records：获取表中的所有记录
filter_sql_query：对单个表进行简单的过滤
execute_sql_query：带有JOIN和子查询的复杂查询

数据操作

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集成到其他系统中

贡献

欢迎贡献！以下是贡献步骤：

Fork该项目
创建功能分支
提交更改
推送到分支
打开Pull Request

许可证

此MCP服务器采用MIT许可证。