Grist MCP服务器
](https://pypi.org/project/mcp-server-grist/) ](https://pypi.org/project/mcp-server-grist/) 
用于与GRIST API交互的MCP（模型上下文协议）服务器。该服务器允许直接从语言模型（如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 suivants的Les包：
fastmcp,httpx,pydantic,python-dotenv
飞行中使用
通过UVX（推荐）
使用UVX，环境和软件包下载在运行时动态完成
uvx mcp-server-grist与支持MCP协议的您喜爱的IA助手一起使用
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 通过脚本的绝对路径 start.js 此包中包含的Node.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撰写
要并行部署多种运输方式：
# Configurer les variables d'environnement
cp .env.example .env
# Éditer le fichier .env avec votre clé API
# Lancer les services
docker-compose up配置
环境变量
创建文件 .env 基于 .env.template 具有以下变量：
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（本地主机）而不是0.0.0.0限制对本地网络的访问 - 启用原始验证（
validate_origin）避免DNS重新绑定攻击 - 对于Internet暴露，请使用带有HTTPS的反向代理
功能
- 直接从语言模型访问GRIST数据
- 组织、工作区、文档、表格和列列表
- 记录管理（创建、播放、更新、删除）
- 具有高级查询功能的数据过滤和排序
- SQL查询支持（仅限选择）
- 通过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查询
- 通用过滤器的简化接口 - 支持排序和限制 - 基本条件
execute_sql_query：复杂SQL查询
- 自定义SQL查询 - 支持加入和子请求 - 可配置设置和超时
访问管理
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：列出文档的webhookcreate_webhook：创建webhookmodify_webhook：修改webhookdelete_webhook：删除webhookclear_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="utilisateur@exemple.com",
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数据的工作流
- 通过Webhooks将Grist与其他系统集成
贡献
欢迎捐款！以下是如何做出贡献：
- 分叉项目
- 为您的功能创建分支
- 提交您的更改
- 向分支推
- 打开拉取请求
许可证
此MCP服务器根据MIT许可。