NocoDB MCP Server

A Model Context Protocol (MCP) server that provides a comprehensive interface to NocoDB - the open source Airtable alternative. This server enables AI agents to interact with NocoDB databases, making it perfect for storing and managing operational data across multiple AI teams.

Features

Database Operations: List and manage NocoDB bases/projects
Table Management: Create, list, and delete tables with custom schemas
Column Management: Add columns to existing tables with full type support
Record CRUD: Full create, read, update, delete operations on records
Advanced Queries: Filter, sort, search, and aggregate data
View Management: Create and use different views (Grid, Gallery, Form, etc.)
Bulk Operations: Insert multiple records at once
File Attachments: Upload files locally or from URLs, attach to records

Installation

Via NPM (Global)

npm install -g @andrewlwn77/nocodb-mcp

Via NPX (No installation)

npx @andrewlwn77/nocodb-mcp

Configuration

Environment Variables

Create a .env file in your project root:

# Required
NOCODB_BASE_URL=http://localhost:8080
NOCODB_API_TOKEN=your_api_token_here

# Optional
NOCODB_DEFAULT_BASE=your_default_base_id

Getting Your API Token

Log into your NocoDB instance
Click on your profile icon
Select "API Tokens"
Create a new token with appropriate permissions

MCP Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nocodb": {
      "command": "npx",
      "args": ["@andrewlwn77/nocodb-mcp"],
      "env": {
        "NOCODB_BASE_URL": "http://localhost:8080",
        "NOCODB_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "nocodb": {
      "command": "nocodb-mcp",
      "env": {
        "NOCODB_BASE_URL": "http://localhost:8080",
        "NOCODB_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Available Tools

Database Operations

list_bases - List all available databases/projects
get_base_info - Get detailed information about a specific base

Table Management

list_tables - List all tables in a base
get_table_info - Get table schema and column information
create_table - Create a new table with custom schema
delete_table - Delete a table
add_column - Add a new column to an existing table
delete_column - Delete a column from a table

Record Operations

insert_record - Insert a single record
bulk_insert - Insert multiple records at once
get_record - Retrieve a specific record by ID
list_records - List records with filtering and pagination
update_record - Update an existing record
delete_record - Delete a record
search_records - Full-text search across records

Query Operations

query - Advanced filtering with multiple conditions
aggregate - Perform SUM, COUNT, AVG, MIN, MAX operations
group_by - Group records by a column

View Management

list_views - List all views for a table
create_view - Create a new view
get_view_data - Get records from a specific view

File Attachments

upload_attachment - Upload a local file to NocoDB storage
upload_attachment_by_url - Upload files from URLs
attach_file_to_record - Upload and attach a file to a record
get_attachment_info - Get attachment information from a record

Usage Examples

Creating a Table

{
  "tool": "create_table",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "customers",
    "columns": [
      {
        "title": "Name",
        "uidt": "SingleLineText",
        "rqd": true
      },
      {
        "title": "Email",
        "uidt": "Email",
        "unique": true
      },
      {
        "title": "Revenue",
        "uidt": "Number",
        "dt": "decimal"
      },
      {
        "title": "Status",
        "uidt": "SingleSelect",
        "dtxp": "'active','inactive','pending'"
      }
    ]
  }
}

Adding Columns to Existing Tables

The add_column tool allows you to dynamically add columns to existing tables. Here are some examples:

Basic Column Types

{
  "tool": "add_column",
  "arguments": {
    "table_id": "table_id_here",
    "title": "Description",
    "uidt": "LongText"
  }
}

Column with Constraints

{
  "tool": "add_column",
  "arguments": {
    "table_id": "table_id_here",
    "title": "Product Code",
    "uidt": "SingleLineText",
    "unique": true,
    "rqd": true
  }
}

Select Column with Options

{
  "tool": "add_column",
  "arguments": {
    "table_id": "table_id_here",
    "title": "Priority",
    "uidt": "SingleSelect",
    "meta": {
      "options": [
        {"title": "Low", "color": "#059669"},
        {"title": "Medium", "color": "#d97706"},
        {"title": "High", "color": "#dc2626"},
        {"title": "Critical", "color": "#7c3aed"}
      ]
    }
  }
}

Currency Column

{
  "tool": "add_column",
  "arguments": {
    "table_id": "table_id_here",
    "title": "Price",
    "uidt": "Currency",
    "meta": {
      "currency_code": "USD"
    }
  }
}

For more column type examples, see Column Types Examples.

Deleting Columns

The delete_column tool allows you to remove columns from existing tables. You can identify the column to delete by either its ID or name.

Delete by Column ID

{
  "tool": "delete_column",
  "arguments": {
    "table_id": "table_id_here",
    "column_id": "column_id_to_delete"
  }
}

Delete by Column Name

{
  "tool": "delete_column",
  "arguments": {
    "table_id": "table_id_here",
    "column_name": "ColumnToDelete"
  }
}

Note: The tool will search for columns matching either the column_name or title field, making it flexible for different naming conventions.

Inserting Records

{
  "tool": "insert_record",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "customers",
    "data": {
      "Name": "Acme Corp",
      "Email": "contact@acme.com",
      "Revenue": 50000,
      "Status": "active"
    }
  }
}

Querying with Filters

{
  "tool": "query",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "customers",
    "where": "(Status,eq,active)~and(Revenue,gt,10000)",
    "sort": ["-Revenue", "Name"],
    "fields": ["Name", "Email", "Revenue"],
    "limit": 10
  }
}

Aggregating Data

{
  "tool": "aggregate",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "customers",
    "column_name": "Revenue",
    "function": "sum",
    "where": "(Status,eq,active)"
  }
}

File Upload Examples

Upload a Local File

{
  "tool": "upload_attachment",
  "arguments": {
    "file_path": "/path/to/document.pdf",
    "storage_path": "documents/2024"
  }
}

Upload from URL

{
  "tool": "upload_attachment_by_url",
  "arguments": {
    "urls": [
      "https://example.com/image1.png",
      "https://example.com/image2.jpg"
    ],
    "storage_path": "images"
  }
}

Attach File to Record

{
  "tool": "attach_file_to_record",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "products",
    "record_id": "42",
    "attachment_field": "ProductImages",
    "file_path": "/path/to/product-photo.jpg"
  }
}

Get Attachment Information

{
  "tool": "get_attachment_info",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "products",
    "record_id": "42",
    "attachment_field": "ProductImages"
  }
}

NocoDB Field Types

Supported UI data types (uidt) for columns:

Basic Types

SingleLineText - Short text field
LongText - Multi-line text
Number - Integer numeric values
Decimal - Decimal numbers with precision
Checkbox - Boolean true/false

Date & Time

Date - Date without time
DateTime - Date with time
Time - Time only
Duration - Time duration

Specialized Text

Email - Email addresses with validation
URL - Web links
PhoneNumber - Phone numbers (note: use "PhoneNumber" not "Phone")

Numeric Types

Currency - Money values (requires meta.currency_code)
Percent - Percentage values
Rating - Star rating

Selection Types

SingleSelect - Dropdown with single selection (requires meta.options)
MultiSelect - Multiple selections (requires meta.options)

Advanced Types

Attachment - File uploads
JSON - JSON data storage

Virtual/Computed Columns

Formula - Calculated fields
Rollup - Aggregate related records
Lookup - Lookup values from related records
QrCode - Generate QR codes (requires meta.fk_qr_value_column_id)
Barcode - Generate barcodes (requires meta.fk_barcode_value_column_id)

Relational

LinkToAnotherRecord - Relationships between tables
Links - Many-to-many relationships

Special Parameters for Column Types

Some column types require additional parameters in the meta field:

SingleSelect/MultiSelect: meta.options array with {title, color} objects
Currency: meta.currency_code (e.g., "USD", "EUR")
QrCode: meta.fk_qr_value_column_id - ID of column to encode
Barcode: meta.fk_barcode_value_column_id - ID of column to encode, optional meta.barcode_format

Filter Syntax

NocoDB uses a specific syntax for filtering:

(field,operator,value) - Basic condition
~and - AND operator
~or - OR operator
~not - NOT operator

Operators

eq - Equal to
neq - Not equal to
gt - Greater than
ge - Greater than or equal
lt - Less than
le - Less than or equal
like - Contains (use % for wildcards)
nlike - Does not contain
null - Is null
notnull - Is not null

Examples

(Status,eq,active) - Status equals "active"
(Revenue,gt,1000)~and(Status,eq,active) - Revenue > 1000 AND Status = "active"
(Name,like,%Corp%) - Name contains "Corp"

Development

Building from Source

# Clone the repository
git clone https://github.com/your-org/nocodb-mcp.git
cd nocodb-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Running Tests

npm test

Error Handling

The server provides detailed error messages for common issues:

Invalid API token
Base/table not found
Invalid column types
Network connectivity issues
Rate limiting

Best Practices

Use Views: Create views for commonly accessed data subsets
Batch Operations: Use bulk_insert for multiple records
Field Selection: Specify only needed fields to reduce payload size
Pagination: Use limit/offset for large datasets
Caching: Consider caching frequently accessed data on the client side

Limitations

Some advanced NocoDB features may not be exposed through this interface
Rate limits depend on your NocoDB instance configuration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

For issues and feature requests, please create an issue on the GitHub repository.