Baserow Schema MCP

mcp-baserow-schema

Baserow 用 MCP サーバー：2FA 認証（TOTP）と OpenAPI 検証に対応した、汎用 Baserow API クライアントです。

1 つのツールで、Baserow REST API 全体を利用できます。テーブル、フィールド、ビュー、フィルターなどのスキーマ変更、行の CRUD、ワークスペース管理など、OpenAPI 仕様に記載されたあらゆる操作を呼び出せます。JWT 認証は自動的に処理されます。

理由

Baserow の公式 MCP は厳選されたデータ CRUDに対応していますが、API 全体（スキーマ変更、ビュー、フィルター、管理者向けエンドポイント）には対応していません。2026 年の今、2FA のない単純なパスワード認証は受け入れられません。この MCP は、次の 2 つの課題を解決します。

• API 全体へのアクセス：同梱の Baserow OpenAPI 仕様に含まれる任意のエンドポイントを、1 つの汎用ツールで利用できます
• 2FA サポート：TOTP ベースの認証を自動処理するため、トークンを手動で管理する必要はありません
• OpenAPI ガード：リクエストは仕様に照らして検証されます。パスを誤って入力した場合は、原因不明の 404 ではなくヒントが表示されます
• エージェント向けに設計：AI エージェントが人間の介入なしにテーブル構造を変更できます

ツール（2）

baserow_api

任意の Baserow API エンドポイントに対応する汎用 HTTP クライアントです。

パラメーター	型	説明
method	GET | POST | PATCH | DELETE | PUT	HTTP メソッド
path	string	/api/ で始まる API パス
body	object, optional	POST/PATCH/PUT 用の JSON ボディ
query	object, optional	文字列のキーと値の組み合わせによるクエリパラメーター

例：

GET    /api/database/tables/database/123/                    → list tables in database 123
POST   /api/database/views/table/456/       {name, type}     → create view
POST   /api/database/views/789/filters/     {field, type, value} → create filter
DELETE /api/database/tables/456/                             → delete table
PATCH  /api/database/rows/table/456/11/    {status}   ?user_field_names=true → update row
POST   /api/database/rows/table/456/batch/ {items:[...]}      → batch update

認証は自動的に処理されます。メソッド、パス、および必要に応じてボディやクエリを指定するだけです。OpenAPI 仕様でパスやメソッドが認識されない場合、類似したパスを含む警告（⚠️ OpenAPI spec: ...）が応答の先頭に付加されます。リクエスト自体は引き続き実行されます（検証はブロックしません）。

auth_status

現在の認証状態（認証済みかどうか、トークンの有効期限、アクセストークンとリフレッシュトークンの残り有効期間）を返します。認証のライフサイクルのデバッグに便利です。

OpenAPI 検証

サーバーには Baserow の公式 OpenAPI 仕様（v2.2.2、275 個のパス、リポジトリのルートにある openapi.json）が同梱されています。各リクエストの前に、次のように検証されます。

• パスとメソッドが見つかった場合 → 警告なしでリクエストが進みます。
• パスは存在するが、メソッドが誤っている場合 → そのパスで使用可能なメソッドの一覧を警告に表示します。
• パスが不明な場合 → 警告に加えて、仕様から類似するパスを最大 5 件表示します。

仕様は dist/../openapi.json から遅延読み込みされます。ファイルが見つからない場合は検証を問題なくスキップし、リクエストは未検証のまま進みます。

認証

Baserow の 2 段階 2FA フローに対応しています。

1. POST /api/user/token-auth/ → 一時的な 2FA トークン（約 60 秒）
2. POST /api/two-factor-auth/verify/（TOTP コードを使用）→ JWT access_token + refresh_token
3. POST /api/user/token-refresh/ → 新しい access_token をサイレントに取得（2FA は不要）

トークンのライフサイクル：

• access_token：約 10 分（JWT の exp クレームから有効期限を読み取り、有効期限の 2 分前に更新）
• refresh_token：約 7 日（有効期限の 5 分前に 2FA で再ログイン）
• temp_token：約 60 秒（2FA 検証ステップでのみ使用）

認証情報は環境変数を介して渡されます。ハードコードされることはありません。

セットアップ

前提条件

• Node.js ≥ 20
• 2FA が有効な Baserow アカウント
• Baserow TOTP シークレット（base32）

インストール

git clone [email protected]:aficiomaquinas/mcp-baserow-schema.git
cd mcp-baserow-schema
npm install
npm run build

設定

環境変数を設定します（または .env ファイルを使用します。.env.example を参照してください）。

BASEROW_API_URL=https://your-baserow-instance.com
[email protected]
BASEROW_PASSWORD=your_password
BASEROW_TOTP_SECRET=YOUR_BASE32_TOTP_SECRET

Hermes Agent

~/.hermes/profiles/<profile>/config.yaml に追加します。

mcp_servers:
  baserow-mcp:
    command: node
    args:
      - /path/to/mcp-baserow-schema/dist/index.js
    enabled: true
    env:
      BASEROW_API_URL: https://baserow.example.com
      BASEROW_USERNAME: [email protected]
      BASEROW_PASSWORD: your_password
      BASEROW_TOTP_SECRET: YOUR_BASE32_TOTP_SECRET

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "baserow-schema": {
      "command": "node",
      "args": ["/path/to/mcp-baserow-schema/dist/index.js"],
      "env": {
        "BASEROW_API_URL": "https://baserow.example.com",
        "BASEROW_USERNAME": "[email protected]",
        "BASEROW_PASSWORD": "your_password",
        "BASEROW_TOTP_SECRET": "YOUR_BASE32_TOTP_SECRET"
      }
    }
  }
}

フィールド型

baserow_api はパススルー型のクライアントなので、Baserow のすべてのフィールド型に対応しています。JSON ボディをエンドポイントの API 契約に合わせるだけです。フィールド型の一覧：

text、long_text、url、email、number、rating、boolean、date、last_modified、last_modified_by、created_on、created_by、duration、link_row、file、single_select、multiple_select、phone_number、formula、count、rollup、lookup、multiple_collaborators、uuid、autonumber、password、ai

エンドポイントの詳細については、同梱の openapi.json または Baserow API ドキュメントを参照してください。

公式 Baserow MCP との併用

v2 以降、この MCP はデータ操作（行、バッチ、検索、並べ替え）もカバーするため、公式 Baserow MCP は任意です。

• mcp-baserow-schema → すべて：スキーマ、データ、ビュー、フィルター、管理
• 公式 Baserow MCP → データ操作にこちらを使いたい場合に便利な、厳選された行の CRUD UX

両方を同時に実行しても問題ありません。互いに競合しません。

リリース

メンテナーの方は、docs/RELEASING.md をご覧ください。リリースは完全に自動化されています（release-it + OIDC 信頼済み公開を使用した GitHub Actions）。バージョン、タグ、server.json は手動で変更しないでください。

ライセンス

MIT