# 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](../nocodb-mcp-connector) 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+.

```bash
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)

```bash
nocodb-mcp-connector
```

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

```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](../nocodb-mcp-connector/README.md#verifying-against-your-instance)
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):

```bash
python -m nocodb_mcp_connector.stdio
```

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

```bash
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"}}}'
```