Gridbase

io.github.CloudCorpRecordsPublished by GitHub account CloudCorpRecordsv0.1.0Updated Nov 1, 2026

Bases, tables, and records in Airtable: list, search, create, update, delete.

VerifiedSTDIODesktop onlyDatabasesProductivity & Workflow

Overview

AI-generated overview

Airtable workbench MCP server that lets an assistant browse bases, tables and records and create, update or delete them.

What you can do
  • List accessible bases and inspect tables, fields and views at a chosen detail level
  • List, filter by formula, text-search and fetch individual records
  • Create, update and delete records in a table
  • Create tables and fields, and rename or re-describe existing tables and fields
  • Add comments to records and list a record's comments with pagination
When to use it
Useful when an assistant needs to read or maintain data in Airtable bases — looking up records, running formula filters, bulk-updating statuses, or adjusting table schemas — without leaving the chat.
Requirements
Runs locally over stdio via npx or the Docker image. Requires an Airtable personal access token in the AIRTABLE_API_KEY environment variable, with schema.bases:read and data.records:read scopes at minimum plus matching write scopes for write tools. Network access to the Airtable API.
Before you install
The token grants access to every base it can reach, so scope it narrowly. Write tools create, update and delete records, tables and fields, and add comments; deletions are not reversible through this server. Record data and comments are sent to the Airtable API.

Installation

In SourceWeft

  1. Open Gridbase in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

gridbase

gridbase is a workbench for Airtable. It walks a base the way a person would: first the list of bases a token can reach, then the tables inside one base and the fields and views each table declares, then the records themselves — listed, filtered by formula, searched by text, or fetched one at a time. The same surface writes back: records can be created, updated, and deleted, tables and fields can be created and renamed, and comments can be attached to records and read again. One binary serves a command-line interface and a stdio MCP server.

An Airtable personal access token is required. Put it in the AIRTABLE_API_KEY environment variable; it is sent to the API as an Authorization: Bearer header and never appears in output. When the variable is missing, every call fails with an error that names it, before any request is made. The token needs the schema.bases:read and data.records:read scopes at minimum, plus the matching write scopes for the write tools.

Install

bash
npx @reneturcios/gridbase bases

Or run the container image:

bash
docker run -i -e AIRTABLE_API_KEY ghcr.io/cloudcorprecords/gridbase

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

bash
export AIRTABLE_API_KEY="pat..."
gridbase basesgridbase tables appXXXXXXXXXXXXXX --detail fullgridbase describe appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXXgridbase records appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX --max 25 --filter "{Status}='Open'"gridbase search appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX "quarterly report"gridbase get appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX recXXXXXXXXXXXXXXgridbase create appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX '{"Name":"New task","Status":"Open"}'gridbase update appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX '[{"id":"recXXXXXXXXXXXXXX","fields":{"Status":"Done"}}]'gridbase delete appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX recXXXXXXXXXXXXXXgridbase create-table appXXXXXXXXXXXXXX Reports '[{"name":"Title","type":"singleLineText"}]'gridbase comment appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX recXXXXXXXXXXXXXX "Looks good"gridbase comments appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX recXXXXXXXXXXXXXX --page-size 10
gridbase --version

Each command prints the upstream JSON payload. Exit codes: 0 on success, 1 when a call fails (including a missing AIRTABLE_API_KEY or an API error), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

bash
npx -y @reneturcios/gridbase mcp

MCP client configuration:

json
{  "mcpServers": {    "gridbase": {      "command": "npx",      "args": ["-y", "@reneturcios/gridbase", "mcp"],      "env": { "AIRTABLE_API_KEY": "pat..." }    }  }}

Tools

ToolInputWhat it returns
list_bases(none)Every accessible base with its ID, name, and permission level.
list_tablesbaseId (required), detailLevel (optional)Tables in the base, trimmed to the requested detail level.
describe_tablebaseId, tableId (required), detailLevel (optional)One table's fields and views.
list_recordsbaseId, tableId (required), maxRecords, filterByFormula (optional)Records from the table.
search_recordsbaseId, tableId, searchTerm (required), fieldIds, maxRecords (optional)Records whose field values contain the term.
get_recordbaseId, tableId, recordId (required)The single record.
create_recordbaseId, tableId, fields (required)The created record.
update_recordsbaseId, tableId, records (required)The updated records.
delete_recordsbaseId, tableId, recordIds (required)Deletion receipts for each record.
create_tablebaseId, name, fields (required), description (optional)The created table.
update_tablebaseId, tableId (required), name, description (optional)The updated table.
create_fieldbaseId, tableId, name, type (required), description, options (optional)The created field.
update_fieldbaseId, tableId, fieldId (required), name, description (optional)The updated field.
create_commentbaseId, tableId, recordId, text (required), parentCommentId (optional)The created comment.
list_commentsbaseId, tableId, recordId (required), pageSize, offset (optional)The record's comments, newest first.

Airtable offers no text-search endpoint, so search_records lists the table (bounded by maxRecords) and keeps the records whose field values contain the term, restricted to fieldIds when supplied. Schema reads trim the meta payload themselves: tableIdentifiersOnly keeps table IDs and names, identifiersOnly also reduces fields and views to IDs and names, and full (the default) returns everything.

Development

bash
npm installnpm run build   # tsc -> dist/npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.

Source: README.md at commit a86ec9a

Tools

15

list_bases

List every Airtable base the configured token can access, with its ID, name, and permission level.

Takes no parameters.

list_tables

List the tables in a base, with fields and views at the requested level of detail.

ParametersbaseIdrequireddetailLevel

describe_table

Describe one table in a base, returning its fields and views at the requested level of detail.

ParametersbaseIdrequiredtableIdrequireddetailLevel

list_records

List records from a table, optionally filtered by an Airtable formula.

ParametersbaseIdrequiredtableIdrequiredmaxRecordsfilterByFormula

search_records

Search records in a table for a text term, across all text fields or a chosen subset.

ParametersbaseIdrequiredtableIdrequiredfieldIdsmaxRecordssearchTermrequired

get_record

Fetch a single record from a table by its record ID.

ParametersbaseIdrequiredtableIdrequiredrecordIdrequired

create_record

Create a new record in a table from a set of field values.

ParametersbaseIdrequiredfieldsrequiredtableIdrequired

update_records

Update one or more records in a table, setting the given fields on each.

ParametersbaseIdrequiredrecordsrequiredtableIdrequired

delete_records

Delete one or more records from a table by their record IDs.

ParametersbaseIdrequiredtableIdrequiredrecordIdsrequired

create_table

Create a new table in a base with the given name, optional description, and field definitions.

ParametersnamerequiredbaseIdrequiredfieldsrequireddescription

update_table

Update a table's name or description.

ParametersnamebaseIdrequiredtableIdrequireddescription

create_field

Create a new field in a table with the given name and type.

ParametersnamerequiredtyperequiredbaseIdrequiredoptionstableIdrequireddescription

update_field

Update a field's name or description.

ParametersnamebaseIdrequiredfieldIdrequiredtableIdrequireddescription

create_comment

Add a comment to a record, optionally as a reply to an existing comment.

ParameterstextrequiredbaseIdrequiredtableIdrequiredrecordIdrequiredparentCommentId

list_comments

List the comments on a record, newest first, with pagination.

ParametersbaseIdrequiredoffsettableIdrequiredpageSizerecordIdrequired

Version history

1
  1. v0.1.0LatestNov 1, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts