Skip to main content
Glama
nocodb-mcp-connector

nocodb-mcp-connector

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.

Related MCP server: Test MCP Server

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

Available Tools

13 tools
count_recordsB

Count records in a table, optionally matching a filter.

Inputs: table_id (required), where.

create_recordsB

Create one or more records in a table.

Inputs: records (required), table_id (required).

delete_recordsC

Delete one or more records by Id.

Inputs: ids (required), table_id (required).

get_recordB

Get a single record by its Id.

Inputs: table_id (required), record_id (required).

get_table_schemaA

Get full schema for a table: its fields/columns, types, options (e.g. select choices), and relational (Links) fields with their linkFieldId. Call this before creating/updating records so you know valid field names and link field ids.

Inputs: table_id (required).

list_basesA

List NocoDB bases (projects) visible to this API token. Pass workspace_id on NocoDB Cloud if you have multiple workspaces; omit it for self-hosted OSS instances.

Inputs: workspace_id.

list_linked_recordsB

List the records currently linked to a given record through a relational (Links) field.

Inputs: table_id (required), record_id (required), link_field_id (required), limit, +1 more.

list_recordsA

List records from a table, with optional filtering, sorting, field selection, and pagination.

Inputs: table_id (required), sort, limit, where, +3 more.

list_tablesA

List tables within a NocoDB base, including each table's id, name, and type.

Inputs: base_id (required).

list_workspacesA

List NocoDB workspaces visible to this API token. Only relevant on NocoDB Cloud; self-hosted OSS instances typically don't use workspaces — call list_bases directly instead.

Inputs: no named parameters.

update_recordsB

Update one or more existing records. Each record object must include its Id plus the fields to change.

Inputs: records (required), table_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action. list_bases vs list_workspaces are clearly separated by workspace vs base, and descriptions clarify usage. list_records vs get_record differ in list vs single retrieval.

    Naming Consistency5/5

    All tools use verb_noun snake_case (list_bases, create_records, link_records, etc.) with no mixed conventions or vague verbs. The pattern is immediately predictable.

    Tool Count5/5

    13 tools is appropriate for a database connector covering base/table discovery, schema introspection, record CRUD, querying, and link management. Each tool earns its place.

    Completeness4/5

    Core workflows are well-covered: explore bases/tables/schema, then create/update/delete/query records and manage links. Minor gaps include no create/delete base or table, but these may be outside the connector's scope.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that provides tools for programmatically managing Airtable bases, tables, fields, and records through Claude Desktop or other MCP clients.
      12
      291 npm
      75
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A dual-transport MCP server that exposes your API as tools to LLM clients, supporting both stdio transport for local clients like Claude Desktop and HTTP/SSE transport for remote clients like OpenAI's Responses API.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Remote MCP server that auto-generates tools from NocoBase OpenAPI specs to enable full CRUD operations on collections across multiple instances. Supports streamable HTTP transport and API key authentication for secure, natural language interaction with NocoBase deployments.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI assistants to interact with NocoBase instances for managing collections, UI schemas, flow models, and running API operations. It provides both hand-crafted tools and dynamically generated tools from NocoBase's OpenAPI specification.
      23
      11 npm
      MIT