Overview

The NocoDB MCP Server is a lightweight adapter that exposes Model Context Protocol (MCP)-style endpoints in front of a NocoDB instance to enable secure read and write access. It translates standardized MCP requests into NocoDB API calls so applications and integrations can interact with NocoDB tables as if they were native MCP models. This makes it straightforward to connect front-end clients, automation tooling, or agent-driven workflows to your NocoDB data with consistent semantics.

Using an MCP server provides a predictable, RESTful façade over NocoDB that centralizes authentication, logging, and request shaping. It can run as a single-process Node service or inside a container, and is useful when you need programmatic, low-latency CRUD access to NocoDB while applying access controls or transforming requests/responses for downstream systems.

Features

Exposes read and write MCP-style endpoints for NocoDB tables
Translates MCP requests to NocoDB REST API calls
Centralized authentication via API token or environment configuration
Lightweight Node.js implementation suitable for Docker or process managers
Request/response logging for auditing and debugging
Configurable base URL and timeout for the upstream NocoDB instance

Installation / Configuration

Quickstart (Node.js)

Clone the repository and install dependencies:

git clone https://github.com/edwinbernadus/nocodb-mcp-server.git
cd nocodb-mcp-server
npm install

Create a .env file in the project root and set required environment variables:

# .env
NOCO_DB_URL=https://your-nocodb-instance.example.com
NOCO_API_KEY=your_nocodb_api_key_or_token
MCP_SERVER_PORT=3000
MCP_SERVER_TOKEN=supersecret_local_token
REQUEST_TIMEOUT_MS=5000

Start the server:

npm start
# or for development
npm run dev

Docker

A Dockerfile is typically included to run the server in a container. Build and run:

docker build -t nocodb-mcp-server .
docker run -e NOCO_DB_URL=https://your-nocodb \
           -e NOCO_API_KEY=your_nocodb_api_key \
           -e MCP_SERVER_TOKEN=supersecret \
           -p 3000:3000 nocodb-mcp-server

Configuration reference

Variable	Description	Example
NOCO_DB_URL	Base URL of the NocoDB instance	https://nocodb.example.com
NOCO_API_KEY	API key or token for NocoDB authentication	abc123
MCP_SERVER_PORT	Local port the server listens on	3000
MCP_SERVER_TOKEN	Token used by clients to authenticate with MCP server	supersecret
REQUEST_TIMEOUT_MS	Upstream request timeout in milliseconds	5000

Adjust values to suit your deployment and secrets management strategy.

Available Resources

The MCP server typically exposes these HTTP endpoints (path and behavior can be adapted in config):

Endpoint	Method	Purpose
/mcp/read	POST	Read/query rows from a table using MCP read payloads
/mcp/write	POST	Create, update, or delete rows using MCP write payloads
/health	GET	Liveness/health check for orchestration systems

Authentication: pass the server token in the Authorization header as a bearer token:

Authorization: Bearer <MCP_SERVER_TOKEN>

Logging: request/response pairs and upstream NocoDB replies are logged to stdout by default. Configure logging to a file or centralized system in production.

Use Cases

Front-end application reads and edits spreadsheet data

A single-page React app calls the MCP server /mcp/read to fetch rows for a table and /mcp/write to save edits. The server enforces a single token and translates requests to the NocoDB REST API, simplifying client logic.

Server-side automation and integrations

A scheduled job or webhook processor writes rows to a NocoDB table via /mcp/write to create records that trigger business workflows in NocoDB. The MCP server allows consistent request formatting and centralizes API credentials.

Agent/AI tooling with controlled data access

Agent frameworks or LLM-driven agents can query and update database rows through the MCP interface. The server can apply rate limits, logging, and input validation before proxying to NocoDB.

Concrete example — read rows (curl)

curl -X POST https://mcp-server.example.com/mcp/read \
  -H "Authorization: Bearer supersecret" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "projects.my_project.tables.customers",
    "query": { "limit": 50, "where": { "status": "active" } }
  }'

Concrete example — insert a row (curl)

curl -X POST https://mcp-server.example.com/mcp/write \
  -H "Authorization: Bearer supersecret" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "projects.my_project.tables.orders",
    "operations": [
      { "op": "insert", "data": { "customer_id": 123, "amount": 49.99, "status": "new" } }
    ]
  }'

Errors and troubleshooting

Check server logs for upstream NocoDB error details.
Verify NOCO_API_KEY and NOCO_DB_URL are correct and reachable.
Use /health to confirm the MCP server is running; confirm network connectivity to NocoDB.

Contributing and Source

Source code, issues, and further instructions are available on GitHub: https://github.com/edwinbernadus/nocodb-mcp-server

Contributions, bug reports, and feature requests are welcome via GitHub issues and pull requests.

NocoDB MCP Server Read and Write Access