mcp -grist

The Grist MCP Server provides programmatic access to Grist data through a set of tools that let you explore and manipulate your Grist workspace using language models. You can list organizations, workspaces, documents, tables, and columns, as well as query, add, update, and delete records within Grist tables. Authentication is handled via an API key, ensuring that all operations are scoped to your Grist account. Tools are designed to be combined with your preferred language model workflow so you can build natural-language interfaces that read and modify Grist data.

Core capabilities include: listing organizations and workspaces to understand your Grist hierarchy, listing documents and tables to discover your data structure, and listing columns to understand available fields. For data operations, you can list, add, update, and delete records in a Grist table with optional filtering, sorting, and limiting. Record updates and deletions require identifying the specific records by ID. All tool calls return structured results that map to Grist’s data model, enabling seamless integration into prompts and responses from your language model.

To use the server, start it with your Python environment and provide your Grist API key. Then invoke the available tools (e.g., list_documents, list_tables, list_records, add_grist_records, update_grist_records, delete_grist_records) through your MCP client or workflow, passing the required inputs such as doc_id, table_id, and any filters or records payloads as JSON-friendly structures.

Prerequisites:

• Python 3.8+
• Git (optional, for cloning)
• Internet access to install packages from PyPI

Installation steps:

1. Install the Grist MCP server package
   • Using pip (recommended):

pip install mcp-server-grist

2. Install development dependencies if you plan to run from source or contribute:

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

3. Obtain your Grist API key and set the required environment variables:

export GRIST_API_KEY=your_api_key_here
export GRIST_API_HOST=https://docs.getgrist.com/api

4. Run the MCP server (example):

python -m grist_mcp_server

5. Optional: build a container image if you prefer Docker (as shown in the README):

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

Tips and known considerations:

• Ensure your GRIST_API_KEY has the necessary scopes to access the organizations, workspaces, documents, and tables you intend to query or modify.
• The GRIST_API_HOST should point to your Grist API endpoint; the default example uses https://docs.getgrist.com/api.
• When listing or operating on records, you may need to provide exact IDs for doc_id, table_id, and other inputs. Use list_* tools to discover these IDs first.
• If you plan to run the server in a non-interactive environment, consider exporting environment variables in your service manager (systemd, Docker, etc.) and ensure the process has network access to Grist.
• If you encounter authentication or rate-limit issues, verify that the API key is valid, not expired, and that your IP is allowed by Grist if applicable.
• The server’s tools are designed to be combined with prompts from a language model; structure your tool calls to pass JSON-like inputs for filters, records, and IDs to maximize compatibility with model outputs.