Servidor MCP de Grist

Un servidor MCP (Model Context Protocol) para interactuar con la API de Grist. Este servidor permite acceder y manipular datos de Grist directamente desde modelos de lenguaje como Claude.

Estructura del proyecto

mcp-server-grist/
├── docs/                  # Documentation et fichiers de référence
│   └── grist_api.yml      # Documentation de l'API Grist
├── archive/               # Fonctionnalités archivées
│   ├── christmas_order_tool.py     # Outil de commandes de Noël (désactivé)
│   ├── grist_form_tools.py         # Intégration des formulaires (désactivé)
│   └── grist_additional_tools.py    # Outils additionnels (désactivé)
├── grist_mcp_server.py    # Serveur MCP principal
├── requirements.txt       # Dépendances Python
├── setup.py              # Configuration du package
├── Dockerfile            # Configuration Docker
├── .env.template         # Template pour les variables d'environnement
└── README.md             # Documentation

Requisitos previos

Python 3.8+
Una clave de API de Grist válida
Los siguientes paquetes de Python: fastmcp, httpx, pydantic, python-dotenv

Instalación

Mediante pip

pip install mcp-server-grist

Instalación manual

git clone https://github.com/yourusername/mcp-server-grist.git
cd mcp-server-grist
pip install -r requirements.txt

Mediante Docker

docker build -t mcp/grist-mcp-server .

Configuración

Variables de entorno

Cree un archivo .env basado en .env.template con las siguientes variables:

GRIST_API_KEY=votre_clé_api
GRIST_API_HOST=https://docs.getgrist.com/api

Encontrará su clave de API en la configuración de su cuenta de Grist.

Configuración con Claude Desktop

Añada esto a su claude_desktop_config.json:

Versión Python

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

Versión 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"
      ]
    }
  }
}

Funcionalidades

Acceso a datos de Grist directamente desde modelos de lenguaje
Listado de organizaciones, espacios de trabajo, documentos, tablas y columnas
Gestión de registros (creación, lectura, actualización, eliminación)
Filtrado y ordenación de datos con capacidades avanzadas de consulta
Soporte de consultas SQL (solo SELECT)
Autenticación segura mediante clave de API

Herramientas disponibles

Gestión de organizaciones y documentos

list_organizations: Lista las organizaciones
list_workspaces: Lista los espacios de trabajo
list_documents: Lista los documentos

Gestión de tablas y columnas

list_tables: Lista las tablas
list_columns: Lista las columnas
list_records: Lista los registros con ordenación y límite

Manipulación de datos

add_grist_records: Añade registros
update_grist_records: Actualiza registros
delete_grist_records: Elimina registros

Filtrado y consultas SQL

filter_sql_query: Consulta SQL optimizada para filtrado simple
- Interfaz simplificada para filtros comunes
  - Soporte de ordenación y limitación
  - Condiciones WHERE básicas
execute_sql_query: Consulta SQL compleja
- Consultas SQL personalizadas
  - Soporte de JOIN y subconsultas
  - Parámetros y tiempo de espera configurables

Ejemplos de uso

# 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}]
)

Casos de uso detallados

Funciones básicas

list_organizations, list_workspaces, list_documents
- Úselas para navegar por la estructura de Grist
  - Necesarias para obtener los IDs de documentos y tablas
  - Sin parámetros complejos
list_tables, list_columns
- Úselas para explorar la estructura de un documento
  - Útiles para conocer los nombres de las columnas antes de realizar consultas
  - Sin parámetros de filtrado
list_records
- Úsela para obtener todos los registros de una tabla
  - Ordenación simple sobre una sola columna (ej: "name" o "-age")
  - Limitación del número de resultados
  - No admite filtrado (use filter_sql_query en su lugar)

Funciones de filtrado SQL

filter_sql_query
- Úsela para filtros simples sobre una sola tabla
  - Condiciones WHERE básicas (igualdad, comparación)
  - Selección de columnas específicas
  - Ordenación y limitación de resultados
  - Ejemplo: filtrar empleados activos de una organización
execute_sql_query
- Úsela para consultas complejas
  - Uniones entre tablas
  - Subconsultas
  - Agregaciones (GROUP BY, HAVING)
  - Parámetros SQL para seguridad
  - Tiempo de espera personalizable
  - Ejemplo: informes complejos con uniones

Funciones de manipulación

add_grist_records
- Úsela para crear nuevos registros
  - Formato simple: lista de diccionarios
  - No se necesita ID (se generan automáticamente)
  - Ejemplo: añadir nuevos clientes
update_grist_records
- Úsela para modificar registros existentes
  - Requiere el ID de cada registro
  - Actualización parcial posible
  - Ejemplo: actualizar la información de un cliente
delete_grist_records
- Úsela para eliminar registros
  - Requiere la lista de IDs a eliminar
  - Operación irreversible
  - Ejemplo: eliminar registros obsoletos

Casos de uso

El servidor MCP de Grist está diseñado para:

Analizar y resumir datos de Grist
Crear, actualizar y eliminar registros programáticamente
Construir informes y visualizaciones
Responder preguntas sobre los datos almacenados
Conectar Grist con modelos de lenguaje para consultas en lenguaje natural

Contribución

¡Las contribuciones son bienvenidas! Así es como puede contribuir:

Haga un fork del proyecto
Cree una rama para su funcionalidad
Haga commit de sus cambios
Haga push a la rama
Abra una Pull Request

Licencia

Este servidor MCP está bajo licencia MIT.

Grist

Documentación