MCP server

Connect NocoDB to Large Language Models (LLMs) via the Model Context Protocol (MCP).

The Model Context Protocol (MCP) Server lets you connect NocoDB with LLMs that support MCP, such as Claude, Cursor, Windsurf, or Codex. With this integration, LLMs can work directly with your NocoDB base: query and edit records and, on NocoDB Cloud and licensed self-hosted deployments, manage tables, fields, views, workflows, interfaces, permissions, and more.

Available tools

Every edition exposes the record tools. An MCP client can list tables and read their schema, query, count, and aggregate records, read attachments, create, update, and delete records, and add or remove individual links through a link field. Record tools take up to 100 records per call.

หมายเหตุ: Updating a link field through the update tool replaces the whole set, so pass the complete list of linked records you want, or [] to clear it. null is not a link value and leaves the links untouched. The link and unlink tools add or remove individual links without restating the set.

On NocoDB Cloud and licensed self-hosted deployments, the server also exposes tools for the rest of the workspace. Each tool wraps the same service as the matching REST API, so validation, permissions, and audit behave identically.

หมายเหตุ: Linking by display value matches exactly and adds to the existing links. A value that matches no record, or that matches more than one, is reported back instead of being linked, so link by record id where titles repeat. Updating by condition requires a condition: there is no form of it that updates every record.

หมายเหตุ: Conditions on a form field and on a Record-Level Security policy are written as one flat list. If those conditions are already grouped, the tool that replaces them refuses the call and leaves them as they are, so edit them in the form view or in the policy itself. View filters and record colour conditions do accept nested groups.

หมายเหตุ: Tools respect the token owner's base role: viewers can read, editors can write records, views, filters, and sorts, and creators can change schema. Tools for plan-gated features appear only when the workspace plan includes the feature, and Record-Level Security policies apply to MCP requests.

หมายเหตุ: In the Community Edition, the MCP server exposes the record tools only.

Connection tools and access

Outside the Community Edition, an MCP connection is created against your account rather than a single base, and you choose what it is allowed to do when you create it. One connection is meant for one MCP client.

Access is where the connection reaches: add the bases it may use, or grant it all resources.

Tools & Permissions is an allowlist of the tools the connection may call. A tool you do not allow is never registered, so it does not appear in the client's tool list at all. Each section is set to Read , Read & write , Read, write & delete , or None ; expand one to allow individual tools instead.

A connection can be changed after it is created. Open it from the list, or use Edit connection in its row menu, to rename it or change its Access and Tools & Permissions ; the change applies on the client's next call and the key stays the same. The key itself is shown only when a connection is created or regenerated.

A connection can never do more than you can. Its authority is what you picked, intersected with your own roles, and it is resolved on every tool call, so a role change applies from the next call onwards. Two things sit outside the access list: a base the connection creates is always reachable by it, and creating a workspace is not offered to MCP connections at all.

หมายเหตุ: Connections created before scopes existed keep working and carry your own access to the one base they were created for. To bound one, delete it and create a new connection.

Desktop LLM Clients

Each MCP endpoint in NocoDB provides a secure URL that can be linked to an MCP-compatible client. Once configured, the LLM can execute database operations in your workspace through natural language prompts, without writing SQL or scripts.

Server Configuration (NocoDB)

1. Open Account Settings and select the MCP tab.
2. Click New connection .
3. Provide a name for the connection.
4. Under Access , add the bases it may reach, or grant access to all resources.
5. Under Tools & Permissions , allow the tools this connection may call.
6. Click Create connection to generate the MCP Config JSON.
7. Copy the generated JSON configuration. This will be used in your LLM client configuration.

A base's MCP Server screen lists the connections that reach that base and creates new ones pinned to it, so Access is not shown there, whether you are creating a connection or editing one. Change a connection's access from the MCP tab in Account Settings .

In the Community Edition, connections are created per base instead:

1. Click on the Overview button in the left sidebar.
2. Select the Settings tab.
3. Select the Model Context Protocol
4. Click on the New MCP Endpoint to create a new MCP config JSON for your base.
5. Provide a name for the MCP endpoint
6. Click Create to generate the MCP Config JSON.
7. Copy the generated JSON configuration. This will be used in your LLM client configuration.

Client Configuration

Claude

1. Open Claude Desktop Preferences (⌘+,).
2. Under Develop , click Edit Config .
3. Insert the JSON block copied here as claude_desktop_config.json.
4. Save the file and restart Claude Desktop.

Cursor

1. Go to Cursor Settings (⇧+⌘+J).
2. Open the MCP tab and select Add Custom MCP .
3. Paste the JSON block copied here . Save.

หมายเหตุ: On success, you will see the number of tools enabled below the MCP Server just installed. If you see an error, double-check the JSON configuration.

Windsurf

1. Open Windsurf Settings (⌘+,).
2. In the Cascade section > Plugins (MCP Server) > Click Manage Plugins
3. Paste the JSON block copied here . Save.

AntiGravity

1. Click the three dots in the top right of the agent window and select MCP Servers .
2. Click Manage MCP Servers .
3. Click View raw config .
4. Paste the JSON block copied here into the file that opens. Save.

Codex

Codex CLI connects to the MCP endpoint over HTTP directly, so it needs no mcp-remote bridge and takes a TOML configuration instead of the shared JSON block.

1. Open ~/.codex/config.toml , creating it if it does not exist.
2. Add the TOML block shown in the Codex tab of the MCP endpoint dialog, using the URL and token generated here .
3. Run codex mcp list to confirm the server is connected.

[mcp_servers.NocoDB_MCP]
url = "https://your-domain.com/mcp/<ncId>"
http_headers = { "x-api-key" = "<ncToken>" }

หมายเหตุ: The table key has to be a bare TOML key, so NocoDB replaces any character outside letters, digits, _ , and - in the endpoint name: an endpoint named My Base MCP appears as [mcp_servers.My_Base_MCP] .

JSON Example

{
  "mcpServers": {
    "NocoDB MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-domain.com/mcp/<ncId>",
        "--header",
        "x-api-key: <ncToken>"
      ]
    }
  }
}

หมายเหตุ: The MCP endpoint also accepts the token in an xc-mcp-token header, so existing configurations using it keep working.

ข้อควรระวัง: Your MCP configurations generated above functions as a set of access credentials, granting full control over your NocoDB base. Ensure it remains confidential, never include it in source control, and store it only in secure, protected locations.

Web based LLM Clients (OAuth)

Connect NocoDB to web-based LLM applications using OAuth, enabling seamless database access directly from the browser without requiring desktop client setup. This approach grants granular permission controls and eliminates the need for manual JSON configuration.

The authorization screen carries the same Access and Tools & Permissions pickers as an MCP connection, so a client reaches only the bases you add and calls only the tools you allow. It starts at Read & write on Records & data and at Read everywhere else.

Some clients name the permissions they need in the authorization request itself, as <category>:<level> pairs such as records:read or tables:write , where the level is read, write or delete . When a client does, the screen lists what it asked for under Requested permissions in place of the Tools & Permissions picker, and the list cannot be edited: authorize it as it stands or cancel. Which bases the client reaches is still yours to choose under Access . A permission NocoDB does not offer is listed as such, and authorizing sends the client back an invalid_scope error instead of a grant.

หมายเหตุ: Authorizations granted before these pickers existed keep working and stay limited to the single base they named. To change what a client reaches, disconnect it and authorize again.

Claude Web

OAuth-based integration allows Claude web users to access NocoDB databases through the connectors interface.

Setup Steps

1. Click here to open Claude Web Settings in a new tab.
   • Alternatively, navigate to Settings > Connectors from the Claude Web app.
2. Click Add custom connector .

1. In the "Add custom connector" dialog:
   • Provide a connector name of your choice
   • Enter the MCP endpoint URL: https://app.nocodb.com/mcp
   • Click Add

1. NocoDB Connector will now be listed in "Disconnected" state. Click Connect to initiate the OAuth authorization flow (Opens in a new tab).

1. Authorize Access

   • You will be asked to log in to your NocoDB account (if not already logged in)
   • Under Access , add the bases Claude may reach, or grant it all resources
   • Under Tools & Permissions , allow the tools Claude may call
   • Confirm the permissions Claude will have
     • Access the resources you selected on your behalf
     • Use only the tools you allowed
     • Act with your own permissions in those resources
   • Click Authorize to grant access

   Authorize stays disabled until you have added at least one resource and allowed at least one tool. Where Claude names its own permissions, there is no tool picker and a resource is all that is needed.

หมายเหตุ: This capture predates the Access and Tools & Permissions pickers, which are offered on NocoDB Cloud and licensed self-hosted deployments. Without a licence the screen stays as shown here: a single base selector above the permission summary.

With this, the NocoDB connector will move to "Connected" state in Claude Web. You can now interact with your NocoDB data through Claude web application.

หมายเหตุ: Self-hosted users should replace https://app.nocodb.com with their NocoDB instance URL

Configure Tool Permissions

By default, all tools are set to "Always ask permission" to ensure you have control over each operation Claude performs. You can modify these settings as needed.

Click here to open Claude Web Settings in a new tab. Click Configure on the NocoDB connector to manage tool permissions. Set each tool's permission level using the dropdown menu:

• Always ask permission — Your approval is required every time Claude uses this tool
• Allow unsupervised — Claude can use this tool without requesting approval

To retrieve Workspace & Base information that this connector has access to, use the "Get Base Info" tool.

Using NocoDB Tools in Claude Web

Once configured, you can interact with your NocoDB data conversationally. For example:

• "Show me all projects with deadlines this week"
• "Create a task named 'Review Documentation'"
• "Mark the status of Project X as completed and reassign to John"
• "Provide details of our top 3 sponsors"

Claude will execute these requests using the enabled NocoDB tools, reading from and writing to your database based on the permissions you've granted.

ข้อควรระวัง: OAuth authorization functions as a set of access credentials granting Claude control over the NocoDB resources you selected. Only authorize access to bases and tools you trust Claude to use on your behalf.

ChatGPT

OAuth-based integration enables OpenAI web users (ChatGPT) to securely connect with NocoDB databases through the MCP connector, directly from their browser environment. This provides the same granular access control and eliminates the need for manual configuration or desktop client setup.

Prerequisites

Enable Developer Mode in ChatGPT settings to allow custom connector additions.

1. Open ChatGPT Settings in a new tab.
   • Alternatively, click your Profile Icon → Settings → Settings → Apps & Connectors ).
2. Click Advanced Settings & enable Developer Mode .

Setup Steps

1. Open ChatGPT Settings in a new tab.
   • Alternatively, click your Profile Icon → Settings → Settings → Apps & Connectors ).
2. Click Create button in top right corner of the Connectors modal.
3. In the "New connector" dialog:
   • Provide a connector name of your choice. Optionally, add a description / icon.
   • Enter the MCP Server URL: https://app.nocodb.com/mcp
   • Check the box for I trust this application .
   • Click Create

1. Authorize Access:
   • Log in to your NocoDB account if prompted
   • Under Access , add the bases ChatGPT may reach, or grant it all resources
   • Under Tools & Permissions , allow the tools ChatGPT may call
   • Review and confirm the permissions being requested:
     • Access to the resources you selected on your behalf
     • Use of only the tools you allowed
     • Acting with your own permissions in those resources
   • Click Authorize

Once authorization completes, you will see a confirmation message in ChatGPT Web indicating the NocoDB connector is now connected.

หมายเหตุ: For self-hosted users, replace https://app.nocodb.com with your NocoDB instance URL.

Using NocoDB Tools in OpenAI Web

On the ChatGPT interface, start a new conversation and

• Click the + icon to open the "Tools" menu, enable Developer Mode if not already enabled.
• Click More to find and select the NocoDB connector you created. Toggle to enable it.

Once configured, you can query or update your NocoDB data conversationally. For example:

• “List all open support tickets assigned to me”
• “Add a new contact named ‘Alice Chen’ to the CRM base”
• “Update the status of Order #2456 to ‘Shipped’”
• “Summarize total revenue by month from the Sales base”

ChatGPT executes these actions using the connected NocoDB tools according to the permissions granted.

ข้อควรระวัง: OAuth authorization provides ChatGPT controlled access to the NocoDB resources you selected. Only authorize the bases and tools you trust ChatGPT to manage on your behalf.

Related pages

• APIs & MCP : Programmatic access to NocoDB: REST APIs for data and metadata, and an MCP server for connecting your bases to LLMs.
• Skills : Extend Claude's capabilities with the NocoDB skill for managing nocodb bases through natural language.