AI & LLM Tools

How to Connect NocoDB to AI: MCP Server Setup

J
James Eriksson
··10 min read
Connect NocoDB to AI assistants via MCP: OAuth setup, token authentication, permissions, and real use cases for CRM, analytics, and bulk operations. Step-by-step guide.
TL;DR
  • NocoDB MCP exposes 200+ database operations to AI assistants like Claude, ChatGPT, and Cursor, released in v2025.09.0
  • OAuth works on Cloud/Licensed NocoDB; token-based setup works on Community Edition and self-hosted instances
  • Scope permissions carefully: expose records and workflows, never expose Members/Permissions or Access/Security
  • Real use cases: CRM queries, data analysis, bulk operations, and data cleanup--all without manual UI clicks
  • Rotate tokens every 30 days; common issues are OAuth 404 (bad NC_SITE_URL), token typos, and firewall blocks

Model Context Protocol (MCP) is a new standard that lets AI assistants like Claude, ChatGPT, and Cursor connect directly to your NocoDB database and perform operations autonomously. Instead of you copying data into prompts or clicking through the UI, the AI queries records, creates tables, and runs workflows in real time. Introduced in NocoDB v2025.09.0 in September 2025, MCP transforms your database into an AI-native tool.

What is NocoDB MCP Server and Why You Need It

Before MCP, using your NocoDB data with AI meant manual work: export to CSV, paste into a prompt, wait for analysis, paste results back. MCP removes that friction. It's a standardized protocol that lets large language models call functions on external systems securely.

When you connect NocoDB to an AI assistant via MCP, you expose a defined set of operations. These include reading records, creating and modifying tables, updating workflows, managing views, handling file uploads, and bulk operations. The AI understands your database schema and can make decisions based on live data without manual intervention.

The real value is immediate. Your sales team's CRM becomes accessible to Claude so it summarizes pipeline health in seconds. Your analytics tables become queryable by ChatGPT without opening the UI. Your project management base becomes a tool Cursor can use to understand sprint status while you code. This is especially powerful for non-technical users: no API knowledge required, no webhooks or custom scripts needed.

NocoDB itself has proven adoption: 65.5K GitHub stars and 5.1K forks. The MCP feature exposes 200+ tools across seven areas: Records (36 tools), Tables & Fields (23), Views (33), Workflows (60), Apps & Docs (49), Members & Permissions (24), and Access & Security. Community Edition users get record operations only (36 tools); all other editions unlock the full set.

Two Ways to Connect: OAuth vs. Token-Based Authentication

You have two paths to connect. OAuth is simpler for getting started. Token-based setup gives you granular control and works on Community Edition.

OAuth is the browser-based flow. You click "Connect to NocoDB" in Claude or ChatGPT, your browser opens NocoDB, you log in, select which bases and projects to expose, and authorize. The AI receives a scoped token tied to your account. No config files. No credential management. The downside: OAuth only works on NocoDB Cloud or a licensed (non-Community) self-hosted instance. And you authorize all at once; you can't easily restrict one conversation to specific tables without giving the same access to others.

Token-based setup means you generate a token in NocoDB, add it to a JSON config file on your machine (like .claude_desktop_config.json), restart your client, and you're connected. This works on Community Edition, pinned projects, and self-hosted instances behind firewalls. The trade-off: you must manually scope which projects and tools the token can access before generating it. Too broad, and the AI has access to sensitive data. Too narrow, and it fails on tasks outside its scope. You also own token rotation--generate a new one every 30 days and update the config.

Which to choose? Use OAuth if you're on NocoDB Cloud and want the fastest setup (5 minutes). Use token-based if you run Community Edition, self-host, or want fine-grained access control per project.

OAuth Setup Step-by-Step

OAuth works the same way across Claude, ChatGPT, Cursor, Windsurf, and Copilot. Your browser handles authentication; you never touch credentials.

Claude Desktop

  1. Open Claude Desktop. Go to Settings (gear icon) > Installed Tools or MCPs.
  2. Search for NocoDB or find it in the tools directory.
  3. Click "Add" or "Connect." You're redirected to nocodb.com.
  4. Log in with your NocoDB account.
  5. Grant permissions: "Claude Desktop would like to access your NocoDB bases." Click Authorize.
  6. Select which bases Claude can access. You can choose all or specific ones.
  7. Confirm. You're redirected back to Claude. Connection is live.
  8. Test: Ask Claude, "What tables do I have in NocoDB?" It queries and responds in real time.

ChatGPT

  1. Open ChatGPT web or app. Go to Settings > Integrations or browse the Actions directory (varies by tier).
  2. Search for NocoDB. Click "Install" or "Connect."
  3. Redirected to nocodb.com. Log in. Authorize ChatGPT to access your account. Select bases if prompted.
  4. Return to ChatGPT. Integration is active.
  5. In a new chat, ask ChatGPT to query NocoDB data. "Show me all open tickets from my database."

Cursor (Code Editor)

Cursor is a code editor built on VS Code with native Claude integration.

  1. Go to Cursor Settings > Features > MCP Servers or Extensions.
  2. Add NocoDB MCP or enable if available.
  3. Click Connect, authenticate to NocoDB, authorize, select bases.
  4. In Cursor's Chat while coding, ask database questions: "Find all open bugs in my NocoDB project tracking base." Cursor queries live while you write code.

Windsurf and GitHub Copilot follow the same pattern: Settings > MCP Servers or Extensions > Add NocoDB > Authenticate via your browser.

All OAuth flows use browser-based redirects. No command line. No JSON editing. Connection is automatic.

Token-Based Setup for Community Edition

Token-based setup works on any NocoDB edition and is required for Community Edition. You manually manage scope and credentials.

When to use this: Community Edition, self-hosted NocoDB, instances behind firewalls, or when you want separate tokens for different projects.

Step 1: Create and Scope a Token

  1. Log into NocoDB. Go to Settings > API Tokens or Integrations > MCP Server.
  2. Click "Generate MCP Connection."
  3. Define scope: Select which project(s) the token can access. Then define tool permissions per area:
    • Records: Read, Read & Write, or Read & Write & Delete
    • Tables & Fields: Read only, or Read & Write & Delete
    • Views: Read only or manage
    • Workflows: Read only or execute/create
    • Apps & Docs: Read only or manage
    • Members & Permissions and Access & Security: Typically disabled (never expose to AI)
  4. Click "Generate Token." NocoDB shows a JSON config. Copy it entirely.

Example config:

{
  "type": "stdio",
  "command": "node",
  "args": ["/path/to/nocodb-mcp-server/dist/index.js"],
  "env": {
    "NOCODB_API_TOKEN": "your-generated-token-here",
    "NOCODB_BASE_ID": "your-base-id-here",
    "NC_SITE_URL": "your-nocodb-domain-here"
  }
}

Step 2: Add to Your Client's Config

For Claude Desktop:

  1. Open ~/.claude_desktop_config.json (Mac/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
  2. Paste the config under mcpServers: paste it as a named entry (e.g., "nocodb": {... }).
  3. Save. Restart Claude Desktop completely.

For Cursor: Add to .cursor/mcp.json or Cursor's MCP Servers settings panel using the same config.

Step 3: Test

In Claude or your client, ask: "Show me all records in my Customers table." The AI queries live.

Permissions and Security Best Practices

MCP scopes permissions by area and by operation. Three levels: Read only (safest), Read & Write (allows creation/modification), and Read & Write & Delete (most powerful, most dangerous).

Never expose Members & Permissions or Access & Security to AI. These allow the AI to add users or disable authentication. That's your final line of defense. Never expose workflows that touch salary data, personal information, or critical business logic unless you explicitly need the AI to trigger them.

Scope tokens to specific projects or bases, never to your entire workspace. If a token is compromised (someone gains access to your config file), revoke it immediately and generate a new one.

Rotate tokens every 30 days. Update your client's config with the new token and restart. Go to NocoDB Settings monthly and verify you recognize every active token. Tokens don't expire by default, so revoke old ones explicitly.

For Community Edition, store your token in environment variables, never hardcoded in config files. If you share your code repo, a hardcoded token is exposed to anyone with access.

Real Use Cases and Example Prompts

Four core use cases show why MCP matters.

CRM Quick Lookup: You're on a sales call. Ask Claude: "What deals are in our NocoDB CRM that are closing this month?" Claude queries your Deals table, filters by close date, and reads back live data: "You have 7 deals closing this month: TechCorp ($50K), EnergyPlus ($30K), etc." No clicking. No exporting. Real-time answer.

Data Analysis: Your finance team wants MRR by product line. Ask ChatGPT: "Query my NocoDB Subscriptions table. Group revenue by product_type. Tell me MRR for each." ChatGPT sums revenue grouped by product: "SaaS: $120K, Services: $40K, Support: $15K. Total MRR: $175K."

Bulk Operations: You have 500 customer records and need to add a column "verification_status" and mark existing customers as "verified." Ask Claude: "Create a new field called 'verification_status' in the Customers table. Set it to 'verified' for records where account_age > 2 years." Claude creates the column and updates 500 records in seconds.

Data Cleanup: Your Contact table has duplicates. Ask Cursor: "Find all contacts with duplicate email addresses in my NocoDB base. Show me the duplicates with their names and creation dates." Cursor flags: "jane@example.com appears 3 times. Do you want to merge or delete?"

Common Issues and Troubleshooting

OAuth 404 - Connection Failed

You click "Connect" and get a 404 or blank page. For self-hosted NocoDB, the NC_SITE_URL environment variable doesn't match your actual domain. Check your NocoDB Settings > General for the exact URL. Ensure NC_SITE_URL matches (including https/http, no trailing slash). Restart NocoDB. Try again. If self-hosted behind a firewall, OAuth won't work; use token-based authentication instead.

Token Validation Failed

You add a token to your config, restart the client, and the AI says it can't connect. Double-check the token matches what NocoDB generated. Copy-paste again. Verify NOCODB_BASE_ID: open your base in NocoDB; the URL shows it (nocodb.com/base/abc123xyz...). abc123xyz is your BASE_ID. Check NC_SITE_URL ends with no trailing slash. Tokens can expire; regenerate if needed. Restart your client completely.

Connection Refused

For self-hosted NocoDB, Claude says it can't reach your server. Verify NocoDB is running with docker ps or check your process manager. Test the connection by making an API request to your NocoDB server's health endpoint. If it returns data, the server is reachable. If behind a reverse proxy (nginx, Caddy), ensure it forwards API routes correctly. Check firewall rules. Port 8080 must be open or behind a public reverse proxy. For OAuth, NC_SITE_URL must be a public URL, not localhost.

Node.js Command Not Found

Your config points to /path/to/nocodb-mcp-server/dist/index.js and the client says "node" is not recognized. Install Node.js (v18 or later) from nodejs.org. Verify: node --version. Check the path to the MCP server is correct and absolute, not relative. Update your config.

Rate Limiting

You make multiple queries in succession and get "Rate limit exceeded." NocoDB limits MCP requests (typically 200 per minute). Wait a few minutes. For high-volume automation, use NocoDB's REST API instead of MCP.

Frequently Asked Questions

Can I use NocoDB Community Edition with MCP?

Yes, but only with token-based authentication. OAuth requires a licensed or Cloud NocoDB instance. Community Edition tokens expose record operations (36 tools) but not schema or admin functions.

How many tools does NocoDB MCP expose?

200+ total across seven areas. Community Edition exposes 36 record tools. Other editions unlock all 200+.

Can I revoke MCP access without deleting my data?

Yes. Delete the token in NocoDB Settings > API Tokens, or revoke OAuth in your account settings. Your data stays. The AI just can't access it.

Do I need to restart my AI client after changing MCP permissions?

Yes. After updating token scopes or editing .claude_desktop_config.json, fully close and reopen your client.

Is MCP access secure?

MCP is as secure as your token or OAuth grant. Tokens are long random strings; OAuth is tied to your NocoDB account. Never share tokens. Rotate monthly. Limit scopes to only what the AI needs.

Can I use MCP with self-hosted NocoDB?

Yes. Use token-based authentication. Your instance must be reachable at a URL (public or VPN). Set NC_SITE_URL and generate a token scoped to your project.

Which AI assistants support NocoDB MCP?

Claude (Desktop and Code on web), ChatGPT, Cursor, Windsurf, and GitHub Copilot. Each connects via OAuth (Cloud NocoDB) or token-based config (self-hosted or Community).

The Bottom Line

NocoDB MCP connects your database to AI assistants so they read, analyze, and update data autonomously. OAuth is simpler for cloud-based users. Token-based setup gives you control and works with Community Edition. Define permissions carefully: expose records and workflows, never expose member management or security settings.

For production MCP use, move to managed NocoDB hosting. You get OAuth pre-configured, automatic backups, SSL handled, and uptime SLA guarantees. Check Opsily's managed NocoDB hosting to eliminate operational overhead and focus on using your data.

Move MCP to Production
Managed NocoDB hosting handles OAuth setup, SSL, and uptime SLA so you can focus on connecting AI to your data.
Get Started Free

Ready to self-host your own apps?

One server. Multiple apps. No per-app fees.

Get started →
NocoDB MCP Server Setup: Connect to Claude & ChatGPT