nocodb-mcp

andrewlwn77/nocodb-mcp

3.3

If you are the rightful owner of nocodb-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server that interfaces with NocoDB, an open-source Airtable alternative, enabling AI agents to manage and interact with databases.

Tools

  1. list_bases

    List all available databases/projects.

  2. create_table

    Create a new table with a custom schema.

  3. insert_record

    Insert a single record into a table.

  4. query

    Perform advanced filtering with multiple conditions.

  5. upload_attachment

    Upload a local file to NocoDB storage.

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

  1. Log into your NocoDB instance
  2. Click on your profile icon
  3. Select "API Tokens"
  4. 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 .

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

  1. Use Views: Create views for commonly accessed data subsets
  2. Batch Operations: Use bulk_insert for multiple records
  3. Field Selection: Specify only needed fields to reduce payload size
  4. Pagination: Use limit/offset for large datasets
  5. 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.