Servidor MCP Grist

Um servidor MCP (Model Context Protocol) para interagir com a API do Grist. Este servidor permite acessar e manipular dados do Grist diretamente de modelos de linguagem como o Claude.

Estrutura do projeto

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

Pré-requisitos

Python 3.8+
Uma chave de API Grist válida
Os seguintes pacotes Python: fastmcp, httpx, pydantic, python-dotenv

Instalação

Via pip

pip install mcp-server-grist

Instalação manual

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

Via Docker

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

Configuração

Variáveis de ambiente

Crie um arquivo .env baseado em .env.template com as seguintes variáveis:

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

Você encontrará sua chave de API nas configurações da sua conta Grist.

Configuração com Claude Desktop

Adicione isto ao seu claude_desktop_config.json:

Versão Python

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

Versão 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

Acesso aos dados do Grist diretamente de modelos de linguagem
Listagem de organizações, espaços de trabalho, documentos, tabelas e colunas
Gerenciamento de registros (criação, leitura, atualização, exclusão)
Filtragem e ordenação de dados com capacidades avançadas de consulta
Suporte a consultas SQL (somente SELECT)
Autenticação segura via chave de API

Ferramentas disponíveis

Gerenciamento de organizações e documentos

list_organizations: Lista as organizações
list_workspaces: Lista os espaços de trabalho
list_documents: Lista os documentos

Gerenciamento de tabelas e colunas

list_tables: Lista as tabelas
list_columns: Lista as colunas
list_records: Lista os registros com ordenação e limite

Manipulação de dados

add_grist_records: Adiciona registros
update_grist_records: Atualiza registros
delete_grist_records: Exclui registros

Filtragem e consultas SQL

filter_sql_query: Consulta SQL otimizada para filtragem simples
- Interface simplificada para filtros comuns
  - Suporte a ordenação e limitação
  - Condições WHERE básicas
execute_sql_query: Consulta SQL complexa
- Consultas SQL personalizadas
  - Suporte a JOIN e subconsultas
  - Parâmetros e timeout configuráveis

Exemplos 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 detalhados

Funções básicas

list_organizations, list_workspaces, list_documents
- Use para navegar pela estrutura do Grist
  - Necessárias para obter os IDs de documentos e tabelas
  - Sem parâmetros complexos
list_tables, list_columns
- Use para explorar a estrutura de um documento
  - Úteis para conhecer os nomes das colunas antes de fazer consultas
  - Sem parâmetros de filtragem
list_records
- Use para obter todos os registros de uma tabela
  - Ordenação simples em uma única coluna (ex: "name" ou "-age")
  - Limitação do número de resultados
  - Não suporta filtragem (use filter_sql_query em vez disso)

Funções de filtragem SQL

filter_sql_query
- Use para filtros simples em uma única tabela
  - Condições WHERE básicas (igualdade, comparação)
  - Seleção de colunas específicas
  - Ordenação e limitação de resultados
  - Exemplo: filtrar funcionários ativos de uma organização
execute_sql_query
- Use para consultas complexas
  - Junções entre tabelas
  - Subconsultas
  - Agregações (GROUP BY, HAVING)
  - Parâmetros SQL para segurança
  - Timeout personalizável
  - Exemplo: relatórios complexos com junções

Funções de manipulação

add_grist_records
- Use para criar novos registros
  - Formato simples: lista de dicionários
  - Não é necessário ID (gerados automaticamente)
  - Exemplo: adicionar novos clientes
update_grist_records
- Use para modificar registros existentes
  - Requer o ID de cada registro
  - Atualização parcial possível
  - Exemplo: atualizar as informações de um cliente
delete_grist_records
- Use para excluir registros
  - Requer a lista de IDs a serem excluídos
  - Operação irreversível
  - Exemplo: excluir registros obsoletos

Casos de uso

O servidor MCP Grist foi projetado para:

Analisar e resumir dados do Grist
Criar, atualizar e excluir registros programaticamente
Construir relatórios e visualizações
Responder perguntas sobre os dados armazenados
Conectar o Grist a modelos de linguagem para consultas em linguagem natural

Contribuição

Contribuições são bem-vindas! Veja como contribuir:

Faça um fork do projeto
Crie uma branch para sua funcionalidade
Faça commit das suas alterações
Envie para a branch
Abra uma Pull Request

Licença

Este servidor MCP está licenciado sob a licença MIT.

Grist

Documentação