nocodb-mcp-connector (Python)

An MCP server that exposes a NocoDB base (bases, tables, records, linked records) as tools, so Claude can read/write your NocoDB data the same way it can with the built-in Airtable connector.

Python implementation of this connector. There's also a TypeScript version with the identical tool set — pick whichever fits your stack. This is the primary/maintained one.

Built as a self-serve open-source template: you deploy your own instance with your own NocoDB account and your own auth secret. There's no shared hosted service — each user runs their own copy.

Tools

Same 13 tools as the TypeScript version: list_workspaces, list_bases, list_tables, get_table_schema, list_records, get_record, count_records, create_records, update_records, delete_records, list_linked_records, link_records, unlink_records. Create/update/delete all accept either a single record or a list for batching.

1. Get a free NocoDB instance

Sign up at https://app.nocodb.com (free plan — 50,000 records, well above Airtable's 1,000-record free cap). Import your Airtable base directly (Base -> Import -> Airtable) or start empty. Get an API token: avatar (bottom left) -> Account Settings -> Tokens -> Create New Token.

2. Local setup

Requires Python 3.10+.

python -m venv .venv
.venv\Scripts\activate          # Windows
pip install -e .
cp .env.example .env            # fill in NOCODB_BASE_URL / NOCODB_API_TOKEN

3. Run locally (stdio, for Claude Desktop/Code)

nocodb-mcp-connector

Add it to your MCP client config, e.g. claude_desktop_config.json:

{
  "mcpServers": {
    "nocodb": {
      "command": "C:\\path\\to\\nocodb-mcp-connector-py\\.venv\\Scripts\\python.exe",
      "args": ["-m", "nocodb_mcp_connector.stdio"],
      "env": {
        "NOCODB_BASE_URL": "https://app.nocodb.com",
        "NOCODB_API_TOKEN": "your-token-here"
      }
    }
  }
}

4. Deploy to Render (for claude.ai custom connector)

claude.ai's custom connectors need a public HTTPS URL, so this repo ships an HTTP entry point (nocodb_mcp_connector.http) alongside the local one — a stateless Streamable HTTP server, since NocoDB itself holds all the actual state.

1. Push this repo to GitHub.
2. In Render: New -> Blueprint, point it at the repo (render.yaml is already set up: free plan, pip install -e ., health check on /health).
3. Set the three env vars Render will prompt for:
   • NOCODB_BASE_URL, NOCODB_API_TOKEN — your NocoDB credentials.
   • MCP_AUTH_TOKEN — a secret you generate yourself (openssl rand -hex 32 or similar). This is what stops random people on the internet from hitting your NocoDB data through the public URL — it's checked with a constant-time comparison against the Authorization: Bearer <token> header on every /mcp request.
4. Deploy. Render's free tier sleeps after 15 min idle — expect a ~30-60s cold start on the first request after a gap.
5. In claude.ai: Settings -> Connectors -> Add custom connector.
   • URL: https://<your-app>.onrender.com/mcp
   • Auth: Request headers -> Authorization: Bearer <the same MCP_AUTH_TOKEN>

/health is intentionally left unauthenticated (Render's health check needs to reach it) — it only ever returns "ok", no data.

Notes on the MCP SDK version

This was built against mcp 2.0.0 — the high-level server class is mcp.server.mcpserver.MCPServer (older tutorials referencing FastMCP from mcp.server.fastmcp predate this rename). If you see import errors after a pip install --upgrade mcp, check mcp's changelog for further API moves.

Verifying against your instance

The NocoDB v2 API endpoint shapes here mirror the TypeScript version — see its README for the same caveat: verified against documented behavior, not a live Swagger scrape, so double-check against a real base once you have one.

Smoke test

Stdio (requires the MCP initialize handshake before tools/list will respond — see the TS README for the exact three-line payload):

python -m nocodb_mcp_connector.stdio

HTTP, once running (nocodb-mcp-connector-http or python -m nocodb_mcp_connector.http):

curl http://localhost:3000/health
# "ok"

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'