nocodb-mcp

A Model Context Protocol (MCP) server for NocoDB. Connect Claude Desktop, Cursor, VS Code, or any MCP-compatible client directly to your NocoDB database.

Features

• Full CRUD — list, get, create, update, delete records
• Filtering & sorting — NocoDB where syntax with ~and/~or operators
• Pagination — limit + offset support
• Named table registry — use friendly names instead of table IDs
• Raw API escape hatch — call any NocoDB endpoint directly
• Zero config beyond env vars — works with any NocoDB instance

Tools

| Tool | Description | |------|-------------| | nocodb_list_tables | List registered tables from NOCODB_TABLES | | nocodb_list_records | List records with filtering, sorting, pagination | | nocodb_get_record | Get a single record by ID | | nocodb_create_records | Create one or more records | | nocodb_update_records | Update records (must include Id) | | nocodb_delete_records | Delete records by ID array | | nocodb_count_records | Count records with optional filter | | nocodb_get_table_fields | Get table schema / field definitions | | nocodb_bulk_upsert_records | Bulk upsert records | | nocodb_raw_api | Raw HTTP request to any NocoDB endpoint |

Quick Start

Via npx (no install)

NOCODB_BASE_URL=https://your-nocodb.com \
NOCODB_API_TOKEN=your_token \
npx nocodb-mcp

Claude Desktop config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "nocodb": {
      "command": "npx",
      "args": ["nocodb-mcp"],
      "env": {
        "NOCODB_BASE_URL": "https://your-nocodb.example.com",
        "NOCODB_API_TOKEN": "your_api_token_here",
        "NOCODB_TABLES": "{\"customers\":\"tableId123\",\"orders\":\"tableId456\"}"
      }
    }
  }
}

Claude Code / VS Code MCP config

{
  "servers": {
    "nocodb": {
      "type": "stdio",
      "command": "npx",
      "args": ["nocodb-mcp"],
      "env": {
        "NOCODB_BASE_URL": "https://your-nocodb.example.com",
        "NOCODB_API_TOKEN": "your_api_token_here",
        "NOCODB_TABLES": "{\"customers\":\"tableId123\"}"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | NOCODB_BASE_URL | ✅ | Your NocoDB base URL, e.g. https://noco.example.com | | NOCODB_API_TOKEN | ✅ | API token from NocoDB → Team & Settings → API Tokens | | NOCODB_TABLES | ❌ | JSON map of {"tableName":"tableId"} for named access |

Usage Examples

List records with filter

Use nocodb_list_records with tableId "mrviuw1mt0i4b61", where "(Status,eq,Active)", limit 10

Create a record

Use nocodb_create_records with tableName "customers", records [{"Name":"Alice","Email":"[email protected]"}]

Update a record

Use nocodb_update_records with tableName "customers", records [{"Id":1,"Status":"Inactive"}]

Filter syntax

NocoDB uses a specific where clause format:

(field,op,value)~and(field2,op2,value2)

Operators: eq, neq, gt, ge, lt, le, like, nlike, is, isnot, in, btw, nbtw

Example: (Amount,gt,100)~and(Status,eq,Active)

Sort syntax

Comma-separated field names. Prefix - for descending:

-CreatedAt,Name

Development

git clone https://github.com/YOUR_USERNAME/nocodb-mcp
cd nocodb-mcp
npm install
cp .env.example .env  # fill in your values
npm run build
node dist/index.js

Publishing to npm

npm login
npm publish

License

MIT