Grist

Model Context Protocol (MCP) is an open standard that lets AI assistants access external data. Any MCP-aware tool (such as Claude or ChatGPT) can use Grist’s MCP server to work with your team sites and documents: list and search tables, read and query rows, add or update rows, and create new documents and tables.

[!note] Want to add a Grist connector to Claude?Connect Grist to Claude

For Grist’s built-in AI assistant, seeAI Assistant.

The Grist MCP server is available onHosted Gristand on the full edition ofself-hosted Grist.

[!note] Want to try the full edition? You can try the full edition of Grist free for 30 days.Learn how to turn it on.

Individuals and small companies may qualify for a free activation key for the full edition. See theactivation key FAQ.

GRIST_OIDC_CIMD_ALLOWED_HOSTS=claude.ai,chatgpt.com

[!note] Clients that do not support CIMD Some assistants cannot register themselves through CIMD. For these, set up anOAuth appin Grist and use it with a client of your choice.

- Hosted Grist:https://docs.getgrist.com/api/mcp, one URL for every team site and your personal site.
- Self-hosted Grist:https://<your-grist-host>/api/mcp,your own host; covers every team site and personal site on that instance.

Clients can authenticate in several ways: API keys, service accounts, registeredOAuth apps, and CIMD (Client ID Metadata Documents), the preferred standard that lets a client register itself automatically from a metadata URL instead of being set up in advance.

[!warning] Directory listing pending review The Grist listing in the Claude directory is still under Anthropic review and is not active yet. Until it goes live, use the special ‘Connect Grist to Claude’ link.

[!note] Developer mode required Adding a custom MCP server in ChatGPT needs developer mode. Turn it on underSettings > Apps > Advanced settings.
- In ChatGPT, openSettings > Apps. UnderAdvanced settings, clickCreate app.chatgpt-apps
- Fill in theNew Appform:

- Name:Grist. The icon and description are optional.

- Connection:keepServer URLselected and enterhttps://docs.getgrist.com/api/mcp, orhttps://<your-grist-host>/api/mcpfor self-hosted Grist.
- Authentication:chooseOAuth.
- TickI understand and want to continueto accept the custom-server warning.chatgpt-new-app

Terminal apps (Claude Code, Gemini CLI, and similar)

Most terminal-based assistants add an MCP server with a single command. For Claude Code:

claude mcp add --transport http grist https://docs.getgrist.com/api/mcp

Grist’s consent screen then asks your MCP client for a set of access scopes. Each scope has a label, and the underlying scope name is shown in parentheses.

A client does not have to ask for every permission up front. It can request only what it needs at first, such as read-only access, and you approve that on the consent screen. If a tool later needs more, some clients ask you to approve the extra permission then and there, and carry on once you do. If yours does not, reconnect Grist from your client’s connector settings and approve the wider access.

Choosing which resources your MCP client can access

The same consent screen also asks which Grist resources the client can reach. You have two options:

- All documents (now and in the future).The client can see and act on every team site, workspace, and document your account has access to, including ones you create later. This is the default.
- Selected resources.Pick specific team sites, workspaces, or documents. You can mix levels, for example a whole workspace plus a single document from elsewhere.

Selecting a parent grants access to everything inside it. If you select a workspace, you do not need to also select the documents inside it.

You can change this selection later from the‘Authorized apps’ pagein your Grist account settings, without disconnecting the client. A change can take up to an hour to reach clients you have already connected, such as Claude or ChatGPT. To apply it right away, disconnect and reconnect Grist from that client’s connector settings.

[!note] Note Every tool name is prefixed withgrist_when called (solist_docsisgrist_list_docs). The prefix is omitted in this list for readability.

- list_orgslists your team sites.
- list_workspaceslists workspaces inside a team site.
- list_docslists documents inside a workspace.
- get_doc_inforeturns metadata about a single document.
- get_user_profilereturns the name and email of the account you are connected as.
- helpreturns a short overview of what the server can do.

- “What Grist documents do I have?”
- “Show me everything in my Marketing team site.”

- query_documentruns a natural-language or SQL-style query across the tables in a document.
- list_recordsreturns rows from a single table.
- get_tablesandget_table_columnsdescribe a document’s structure.
- list_snapshotslists older saved versions of a document.
- get_grist_access_rules_referenceexplains how a document’s access rules work.

- “How many open deals are in my CRM?”
- “List contacts I haven’t talked to in 90 days.”
- “What’s total revenue by client this quarter in my Invoices document?”

- add_recordsappends new rows.
- update_recordsmodifies existing rows by row id.
- remove_recordsdeletes rows.

- “Add a new client called Acme Corp to my CRM with the emailops@acme.com.”
- “Mark task #42 as done in my Project Tracker.”
- “Remove every row in Tickets where Status is ‘Archived’.”

- create_docmakes a new document in a workspace.
- create_tableandadd_table_columnextend the schema.
- update_table_columnchanges column type, formula, or label.

Other tools:rename_table,remove_table,remove_table_column.

- “Start a new document for tracking my expenses.”
- “Add a Priority column to Tasks with options Low, Medium, High.”
- “Rename the Notes column to Comments in my CRM.”

- get_pageslists the pages in a document.
- add_page_widgetadds a widget to a page (Table, Card, Card List, Chart, Calendar, Custom, and so on).
- update_page_widgetchanges a widget’s title, table, view configuration, or layout.

Other tools:update_page,remove_page,get_page_widgets,remove_page_widget,get_page_widget_select_by_options,set_page_widget_select_by,get_available_custom_widgets.

- “Add a chart page to my Sales document showing revenue by month.”
- “Put a Card View of Contacts on the Overview page.”
- “Remove the Internal Notes page from my Project Tracker.”

- list_attachmentslists the files in a document, with their name, size, and type.
- get_attachment_urlgives a short-lived link to download one file.

- “What files are attached in my Expenses document?”
- “Give me a download link for the receipt in my Expenses document.”

These examples use Claude.ai. The first time Claude calls a Grist tool, it asks for your approval. You can choose ‘Always allow’ to skip the prompt for that tool on future calls.

- Query structured data in plain language:“In my CRM document, who has an open task due in the next 7 days?”
- Bulk-update records:“In my Deliveries document, update all dates to follow ISO 8601 formatting.”
- Start a document from scratch:“Create a new document called ‘Reviewer Sandbox’ with a Sample table that has the properly-typed columns: Name, Value, Created.”

Once the assistant finishes, the new or updated document is ready to open in Grist.

When you call a Grist tool from your MCP client, the data that the tool returns is sent to that client’s AI provider so the model can use it in its response.

- Transport is HTTPS/TLS end-to-end.
- The MCP server holds no data of its own. Every request is authenticated against your existing Grist account and access rules.
- The OAuth token is scoped to the permissions you granted upon connection. You can revoke it any time from Grist’s account settings.

[!warning] Warning Treat the connector like sharing a document with a colleague. Anything you ask the client to read or write will be visible to its AI provider.

See theGrist Privacy Policyfor details.

Yes. Most MCP clients let you add the same MCP server more than once under different connector names, so you can keep separate connections (for example, signed in as different Grist accounts). In Claude, the directory listing supports only a single connection, but thecustom connector pathdoes not stop you from adding the same URL again under a different name.

First, check which Grist account you used when you connected. If you are not sure, ask the AI something like “which Grist account am I logged in as?” and it will report the connected account’s name and email. If you have several Grist accounts (for example, a personal one and a work one), the document might live under a different account. Opendocs.getgrist.com, confirm the document exists under the account you used to connect, and check that you have at least view access.

Connect your Attio workspace to large language models.