{
  "markdown": "# mcp-baserow-schema\n\nMCP server for Baserow: a **generic Baserow API client** with **2FA authentication** (TOTP) and **OpenAPI validation**.\n\nOne tool, the entire Baserow REST API. Schema changes (tables, fields, views, filters), row CRUD, workspace admin — anything documented in the OpenAPI spec is callable, with JWT auth handled automatically.\n\n## Why\n\nBaserow's official MCP handles curated **data CRUD** but not the full API surface (schema changes, views, filters, admin endpoints). In 2026, plain password auth without 2FA is not acceptable. This MCP solves both:\n\n- **Full API access**: any endpoint from the bundled Baserow OpenAPI spec via one generic tool\n- **2FA support**: automatic TOTP-based authentication — no manual token management\n- **OpenAPI guard**: requests are validated against the spec; mistyped paths get a hint instead of a mystery 404\n- **Designed for agents**: AI agents can modify table structure without human intervention\n\n## Tools (2)\n\n### `baserow_api`\n\nGeneric HTTP client for any Baserow API endpoint.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `method` | `GET` \\| `POST` \\| `PATCH` \\| `DELETE` \\| `PUT` | HTTP method |\n| `path` | string | API path starting with `/api/` |\n| `body` | object, optional | JSON body for POST/PATCH/PUT |\n| `query` | object, optional | Query params as string key-value pairs |\n\nExamples:\n\n```\nGET    /api/database/tables/database/123/                    → list tables in database 123\nPOST   /api/database/views/table/456/       {name, type}     → create view\nPOST   /api/database/views/789/filters/     {field, type, value} → create filter\nDELETE /api/database/tables/456/                             → delete table\nPATCH  /api/database/rows/table/456/11/    {status}   ?user_field_names=true → update row\nPOST   /api/database/rows/table/456/batch/ {items:[...]}      → batch update\n```\n\nAuth is handled automatically: just provide method, path, and optional body/query. If the OpenAPI spec doesn't recognize the path/method, the response is prefixed with a warning (`⚠️ OpenAPI spec: ...`) including similar paths — the request still executes (validation is non-blocking).\n\n### `auth_status`\n\nReturns the current authentication state: authenticated, token expiry, and remaining lifetime of access/refresh tokens. Useful for debugging the auth lifecycle.\n\n## OpenAPI Validation\n\nThe server bundles the official Baserow OpenAPI spec (v2.2.2, 275 paths, `openapi.json` at the repo root). Before each request:\n\n- **Path + method found** → request proceeds silently.\n- **Path exists, method wrong** → warning lists the available methods for that path.\n- **Path unknown** → warning plus up to 5 similar paths from the spec.\n\nThe spec is loaded lazily from `dist/../openapi.json`; if missing, validation is skipped gracefully and requests proceed unvalidated.\n\n## Authentication\n\nSupports Baserow's two-step 2FA flow:\n\n1. `POST /api/user/token-auth/` → temporary 2FA token (~60 s)\n2. `POST /api/two-factor-auth/verify/` (with TOTP code) → JWT access_token + refresh_token\n3. `POST /api/user/token-refresh/` → new access_token, silently (no 2FA needed)\n\nToken lifecycle:\n\n- **access_token**: ~10 minutes (expiry read from the JWT `exp` claim, refreshed 2 min before expiry)\n- **refresh_token**: ~7 days (full 2FA re-login 5 min before expiry)\n- **temp_token**: ~60 seconds (only for the 2FA verify step)\n\nCredentials are passed via environment variables — never hardcoded.\n\n## Setup\n\n### Prerequisites\n\n- Node.js ≥ 20\n- Baserow account with 2FA enabled\n- Baserow TOTP secret (base32)\n\n### Install\n\n```bash\ngit clone git@github.com:aficiomaquinas/mcp-baserow-schema.git\ncd mcp-baserow-schema\nnpm install\nnpm run build\n```\n\n### Configure\n\nSet environment variables (or use a `.env` file — see `.env.example`):\n\n```bash\nBASEROW_API_URL=https://your-baserow-instance.com\nBASEROW_USERNAME=you@example.com\nBASEROW_PASSWORD=your_password\nBASEROW_TOTP_SECRET=YOUR_BASE32_TOTP_SECRET\n```\n\n### Hermes Agent\n\nAdd to `~/.hermes/profiles/<profile>/config.yaml`:\n\n```yaml\nmcp_servers:\n  baserow-mcp:\n    command: node\n    args:\n      - /path/to/mcp-baserow-schema/dist/index.js\n    enabled: true\n    env:\n      BASEROW_API_URL: https://baserow.example.com\n      BASEROW_USERNAME: you@example.com\n      BASEROW_PASSWORD: your_password\n      BASEROW_TOTP_SECRET: YOUR_BASE32_TOTP_SECRET\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"baserow-schema\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-baserow-schema/dist/index.js\"],\n      \"env\": {\n        \"BASEROW_API_URL\": \"https://baserow.example.com\",\n        \"BASEROW_USERNAME\": \"you@example.com\",\n        \"BASEROW_PASSWORD\": \"your_password\",\n        \"BASEROW_TOTP_SECRET\": \"YOUR_BASE32_TOTP_SECRET\"\n      }\n    }\n  }\n}\n```\n\n## Field Types\n\nSince `baserow_api` is a pass-through client, **every Baserow field type** is supported — the JSON body just needs to match the API contract for the endpoint. Reference list of field types:\n\n`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`\n\nEndpoint details: consult the bundled `openapi.json` or the [Baserow API docs](https://api.baserow.io/api/redoc/).\n\n## Usage with Official Baserow MCP\n\nSince v2, this MCP covers data operations too (rows, batches, search, sort), so the official Baserow MCP is **optional**:\n\n- **mcp-baserow-schema** → everything: schema, data, views, filters, admin\n- **Official Baserow MCP** → curated row-CRUD UX, if you prefer it for data work\n\nRunning both side by side is fine; they don't conflict.\n\n## Releasing\n\nMaintainers: see [docs/RELEASING.md](docs/RELEASING.md). Releases are fully automated (release-it + GitHub Actions with OIDC trusted publishing) — never bump versions, tags, or `server.json` manually.\n\n## License\n\nMIT\n",
  "bytes": 6048,
  "sha": "df7bfdbaccd1ab8c7af92adad5724140d9330a5f2cced1d7c9f6149b16ba1534",
  "repo_slug": "aficiomaquinas/mcp-baserow-schema",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aficiomaquinas_mcp_baserow_sch_b8663969/readme"
}