gridbase

gridbase

gridbase は Airtable 用のワークベンチです。人が操作するようにベースをたどります。まずトークンでアクセスできるベースの一覧を取得し、次に 1 つのベース内のテーブルと、各テーブルで定義されているフィールドやビューを確認し、その後レコードを一覧表示、数式で絞り込み、テキストで検索、または 1 件ずつ取得します。同じ機能でデータを書き戻すこともできます。レコードの作成、更新、削除、テーブルやフィールドの作成と名前変更ができ、レコードにコメントを付けて再び読み取ることもできます。1 つのバイナリで、コマンドラインインターフェースと stdio MCP サーバーの両方を提供します。

Airtable の個人用アクセストークンが必要です。トークンを環境変数 AIRTABLE_API_KEY に設定してください。トークンは Authorization: Bearer ヘッダーとして API に送信され、出力には決して含まれません。この変数が設定されていない場合、リクエストを送信する前に、変数名を示すエラーが発生してすべての呼び出しが失敗します。トークンには最低限、schema.bases:read と data.records:read のスコープが必要です。書き込みツールを使用するには、それぞれに対応する書き込みスコープも必要です。

インストール

npx @reneturcios/gridbase bases

または、コンテナーイメージを実行します。

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

コンテナーはデフォルトで MCP サーバーを起動します（下記を参照）。代わりに CLI として使用するには、CLI 引数を渡してください。

CLI

export AIRTABLE_API_KEY="pat..."

gridbase bases
gridbase tables appXXXXXXXXXXXXXX --detail full
gridbase describe appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX
gridbase records appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX --max 25 --filter "{Status}='Open'"
gridbase search appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX "quarterly report"
gridbase get appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX recXXXXXXXXXXXXXX
gridbase create appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX '{"Name":"New task","Status":"Open"}'
gridbase update appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX '[{"id":"recXXXXXXXXXXXXXX","fields":{"Status":"Done"}}]'
gridbase delete appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX recXXXXXXXXXXXXXX
gridbase 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

各コマンドは、上流から返された JSON ペイロードを出力します。終了コード：成功時は 0、呼び出しに失敗した場合（AIRTABLE_API_KEY が設定されていない場合や API エラーを含む）は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

1 つのバイナリで両方のインターフェースを提供します。mcp サブコマンドは stdio MCP サーバーを起動します。

npx -y @reneturcios/gridbase mcp

MCP クライアントの設定：

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

ツール

ツール	入力	返される内容
list_bases	（なし）	アクセス可能なすべてのベースと、その ID、名前、権限レベル。
list_tables	baseId（必須）、detailLevel（任意）	指定された詳細レベルに整えた、ベース内のテーブル。
describe_table	baseId、tableId（必須）、detailLevel（任意）	1 つのテーブルのフィールドとビュー。
list_records	baseId、tableId（必須）、maxRecords、filterByFormula（任意）	テーブル内のレコード。
search_records	baseId、tableId、searchTerm（必須）、fieldIds、maxRecords（任意）	フィールド値に検索語を含むレコード。
get_record	baseId、tableId、recordId（必須）	1 件のレコード。
create_record	baseId、tableId、fields（必須）	作成されたレコード。
update_records	baseId、tableId、records（必須）	更新されたレコード。
delete_records	baseId、tableId、recordIds（必須）	各レコードの削除結果。
create_table	baseId、name、fields（必須）、description（任意）	作成されたテーブル。
update_table	baseId、tableId（必須）、name、description（任意）	更新されたテーブル。
create_field	baseId、tableId、name、type（必須）、description、options（任意）	作成されたフィールド。
update_field	baseId、tableId、fieldId（必須）、name、description（任意）	更新されたフィールド。
create_comment	baseId、tableId、recordId、text（必須）、parentCommentId（任意）	作成されたコメント。
list_comments	baseId、tableId、recordId（必須）、pageSize、offset（任意）	レコードのコメント。新しいものから順に表示されます。

Airtable にはテキスト検索エンドポイントがないため、search_records はテーブルを一覧表示し（maxRecords で上限を設定）、フィールド値に検索語を含むレコードを抽出します。fieldIds が指定されている場合は、そのフィールドに限定されます。スキーマの読み取りでは、メタペイロード自体を整形します。tableIdentifiersOnly はテーブルの ID と名前のみを保持し、identifiersOnly はさらにフィールドとビューを ID と名前だけに絞り、full（デフォルト）はすべてを返します。

開発

npm install
npm 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

ライセンス

MIT — LICENSE を参照してください。