STARWARCLOUD STARWAR.AI
返回市场
诺科数据库-MCP

诺科数据库-MCP

作者：andrewlwn774 星标更新：2025-07-08
安装使用来源：spider==github.com

项目介绍

NocoDB MCP 服务器

这是一个提供与 NocoDB（开源的 Airtable 替代品）全面接口的 Model Context Protocol (MCP) 服务器。此服务器使AI代理能够与 NocoDB 数据库进行交互，非常适合存储和管理多个AI团队的操作数据。

功能

  • 数据库操作：列出并管理 NocoDB 数据库/项目
  • 表管理：创建、列出和删除具有自定义模式的表
  • 列管理：向现有表添加列，并支持完整的类型支持
  • 记录 CRUD：对记录执行完整的创建、读取、更新和删除操作
  • 高级查询：过滤、排序、搜索和聚合数据
  • 视图管理：创建和使用不同的视图（网格、画廊、表单等）
  • 批量操作：一次插入多条记录
  • 文件附件：从本地或URL上传文件，并将其附加到记录中

安装

通过 NPM（全局）

npm install -g @andrewlwn77/nocodb-mcp

通过 NPX（无需安装）

npx @andrewlwn77/nocodb-mcp

配置

环境变量

在你的项目根目录下创建一个 .env 文件：

# 必需
NOCODB_BASE_URL=http://localhost:8080
NOCODB_API_TOKEN=your_api_token_here

# 可选
NOCODB_DEFAULT_BASE=your_default_base_id

获取您的 API Token

  1. 登录到您的 NocoDB 实例
  2. 点击您的个人资料图标
  3. 选择“API Tokens”
  4. 创建一个具有适当权限的新令牌

MCP 配置

添加到您的 Claude Desktop 配置文件中：

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"
      }
    }
  }
}

或者如果已全局安装：

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

可用工具

数据库操作

  • list_bases - 列出所有可用的数据库/项目
  • get_base_info - 获取特定数据库的详细信息

表管理

  • list_tables - 列出数据库中的所有表
  • get_table_info - 获取表模式和列信息
  • create_table - 使用自定义模式创建新表
  • delete_table - 删除表
  • add_column - 向现有表添加新列
  • delete_column - 从表中删除列

记录操作

  • insert_record - 插入单个记录
  • bulk_insert - 一次插入多条记录
  • get_record - 根据ID检索特定记录
  • list_records - 列出记录，带有过滤和分页
  • update_record - 更新现有记录
  • delete_record - 删除记录
  • search_records - 在记录中进行全文搜索

查询操作

  • query - 使用多个条件进行高级过滤
  • aggregate - 执行SUM、COUNT、AVG、MIN、MAX操作
  • group_by - 按列分组记录

视图管理

  • list_views - 列出表的所有视图
  • create_view - 创建新的视图
  • get_view_data - 从特定视图获取记录

文件附件

  • upload_attachment - 将本地文件上传到 NocoDB 存储
  • upload_attachment_by_url - 从URL上传文件
  • attach_file_to_record - 上传并附加文件到记录
  • get_attachment_info - 从记录中获取附件信息

使用示例

创建表

{
  "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",
       [...]
      },
      {
        "title": "Status",
        "uidt": "SingleSelect",
        "dtxp": "'active','inactive','pending'"
      }
    ]
  }
}

向现有表添加列

add_column 工具允许您动态地向现有表添加列。这里有一些例子：

基本列类型

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

带约束的列

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

带选项的选择列

{
  "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"}
      ]
    }
  }
}

货币列

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

更多列类型的示例，请参见 Column Types Examples。

删除列

delete_column 工具允许您从现有表中删除列。您可以根据列ID或名称来识别要删除的列。

通过列ID删除

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

通过列名称删除

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

注意：该工具会搜索匹配 column_name 或 title 字段的列，使其适应不同的命名约定。

插入记录

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

使用过滤器查询

{
  "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
  }
}

聚合数据

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

文件上传示例

上传本地文件

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

从URL上传

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

将文件附加到记录

{
  "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"
  }
}

获取附件信息

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

NocoDB 字段类型

列支持的UI数据类型（uidt）：

基本类型

  • SingleLineText - 短文本字段
  • LongText - 多行文本
  • Number - 整数数值
  • Decimal - 具有精度的小数
  • Checkbox - 布尔值（真/假）

日期和时间

  • Date - 无时间的日期
  • DateTime - 带时间的日期
  • Time - 时间
  • Duration - 时间持续

特殊化文本

  • Email - 带验证的电子邮件地址
  • URL - 网络链接
  • PhoneNumber - 电话号码（注意：使用 "PhoneNumber" 而不是 "Phone"）

数字类型

  • Currency - 货币值（需要 meta.currency_code）
  • Percent - 百分数值
  • Rating - 星级评分

选择类型

  • SingleSelect - 单一选择的下拉菜单（需要 meta.options）
  • MultiSelect - 多重选择（需要 meta.options）

高级类型

  • Attachment - 文件上传
  • JSON - JSON 数据存储

虚拟/计算列

  • Formula - 计算字段
  • Rollup - 汇总相关记录
  • Lookup - 查找相关记录的值
  • QrCode - 生成二维码（需要 meta.fk_qr_value_column_id）
  • Barcode - 生成条形码（需要 meta.fk_barcode_value_column_id）

关系型

  • LinkToAnotherRecord - 表之间的关系
  • Links - 多对多关系

特定参数用于列类型

某些列类型需要在 meta 字段中提供额外的参数：

  • SingleSelect/MultiSelect：meta.options 包含 {title, color} 对象的数组
  • Currency：meta.currency_code（例如："USD"，"EUR"）
  • QrCode：meta.fk_qr_value_column_id - 编码列的ID
  • Barcode：meta.fk_barcode_value_column_id - 编码列的ID，可选 meta.barcode_format

过滤语法

NocoDB 使用特定的语法进行过滤：

  • (field,operator,value) - 基本条件
  • ~and - AND 操作符
  • ~or - OR 操作符
  • ~not - NOT 操作符

操作符

  • eq - 等于
  • neq - 不等于
  • gt - 大于
  • ge - 大于或等于
  • lt - 小于
  • le - 小于或等于
  • like - 包含（使用 % 作为通配符）
  • nlike - 不包含
  • null - 是空
  • notnull - 不是空

示例

  • (Status,eq,active) - 状态等于 "active"
  • (Revenue,gt,1000)~and(Status,eq,active) - 收入 > 1000 并且状态 = "active"
  • (Name,like,%Corp%) - 名称包含 "Corp"

开发

从源代码构建

# 克隆仓库
git clone https://github.com/your-org/nocodb-mcp.git
cd nocodb-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 在开发模式下运行
npm run dev

运行测试

npm test

错误处理

服务器提供了常见问题的详细错误消息：

  • 无效的API令牌
  • 数据库/表未找到
  • 无效的列类型
  • 网络连接问题
  • 速率限制

最佳实践

  1. 使用视图：为经常访问的数据子集创建视图
  2. 批处理操作：使用 bulk_insert 插入多条记录
  3. 字段选择：仅指定所需的字段以减少负载大小
  4. 分页：对于大型数据集使用 limit/offset
  5. 缓存：考虑在客户端缓存频繁访问的数据

限制

  • 某些高级的NocoDB功能可能无法通过此接口访问
  • 速率限制取决于您的NocoDB实例配置

贡献

欢迎贡献！请随时提交Pull Request。

许可证

MIT

支持

对于问题和功能请求，请在GitHub仓库上创建Issue。