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

诺科数据库-MCP服务器

作者：granthooks12 星标更新：2025-04-14
安装使用来源：spider==github.com

项目介绍

Nocodb MCP 服务器

此MCP服务器提供了通过模型上下文协议与Nocodb数据库交互的工具，提供Nocodb表的CRUD操作（创建、读取、更新、删除）。

安装

  1. 安装所需依赖项：
pip install -r requirements.txt
  1. 确保已安装MCP Python SDK（上述依赖项中应已安装）：
pip install "mcp[cli]"

配置

此MCP服务器需要三个环境变量：

  • NOCODB_URL：您的Nocodb实例的基本URL（例如，https://example.com/ncdb）
  • NOCODB_API_TOKEN：用于与Nocodb进行身份验证的API令牌
  • NOCODB_BASE_ID：您的Nocodb数据库的基础ID

您可以通过以下步骤获取API令牌：

  1. 登录到您的Nocodb实例
  2. 转到账户设置 > API令牌
  3. 创建一个具有适当权限的新令牌

基础ID可以在您的Nocodb仪表板的URL中找到：https://your-nocodb.com/dashboard/#/nc/base/YOUR_BASE_ID/table/...

使用方法

与Claude Desktop集成

要与Claude Desktop集成，请在claude_desktop_config.json中添加以下配置：

{
  "mcpServers": {
    "nocodb": {
      "command": "python",
      "args": [
        "path/to/nocodb_mcp_server.py"
      ],
      "env": {
        "NOCODB_URL": "https://your-nocodb-instance.com",
        "NOCODB_API_TOKEN": "your_api_token_here",
        "NOCODB_BASE_ID": "your_base_id_here"
      }
    }
  }
}

或者使用MCP CLI进行安装（推荐）：

# 基本安装
mcp install nocodb_mcp_server.py

# 带有环境变量
mcp install nocodb_mcp_server.py -v NOCODB_URL=https://your-nocodb-instance.com -v NOCODB_API_TOKEN=your_token -v NOCODB_BASE_ID=your_base_id

# 或者使用.env文件
m
mcp install nocodb_mcp_server.py -f .env

作为独立服务器运行

# 安装依赖项
pip install -r requirements.txt

# 直接运行服务器
python nocodb_mcp_server.py

# 或者使用MCP CLI
mcp run nocodb_mcp_server.py

开发模式

为了测试和调试，使用MCP Inspector：

# 在开发模式下运行
mcp dev nocodb_mcp_server.py

在Windows上的Cursor

对于Windows上的Cursor，在您的mcp.json配置文件中使用以下语法：

{
  "mcpServers": {
    "nocodb": {
      "command": "C:\\Path\\To\\Your\\Python\\Executable",
      "args": [
        "C:\\Path\\To\\Your\\nocodb_mcp_server.py"
      ],
      "env": {
        "NOCODB_URL": "http://localhost:8080",
        "NOCODB_API_TOKEN": "your_api_token_here",
        "NOCODB_BASE_ID": "your_base_id_here"
      }
    }
  }
}

提供的工具

服务器提供的工具如下：

1. retrieve_records

从Nocodb表中检索一条或多条记录。

参数：

  • table_name：要查询的表名
  • row_id（可选）：特定行ID以检索单个记录
  • filters（可选）：Nocodb格式的过滤条件
  • limit（可选）：返回的最大记录数（默认：10）
  • offset（可选）：跳过的记录数以实现分页（默认：0）
  • sort（可选）：排序的列
  • fields（可选）：逗号分隔的字段列表以包含

示例：

# 获取表中的所有记录（限制为10）
retrieve_records(table_name="customers")

# 根据ID获取特定记录
retrieve_records(table_name="customers", row_id="123")

# 使用条件过滤记录
retrieve_records(
    table_name="customers", 
    filters="(age,gt,30)~and(status,eq,active)"
)

2. create_records

在Nocodb表中创建一条或多条记录。

参数：

  • table_name：要插入的表名
  • data：包含列值对的字典或用于批量创建的此类字典列表
  • bulk（可选）：设置为True以进行批量创建

示例：

# 创建单个记录
create_records(
    table_name="customers",
    data={"name": "John Doe", "email": "john@example.com", "age": 35}
)

# 批量创建多个记录
create_records(
    table_name="customers",
    data=[
        {"name": "John Doe", "email": "john@example.com", "age": 35},
        {"name": "Jane Smith", "email": "jane@example.com", "age": 28}
    ],
    bulk=True
)

3. update_records

更新Nocodb表中的一条或多条记录。

参数：

  • table_name：要更新的表名
  • row_id：要更新的记录ID（单个记录更新时必需）
  • data：包含要更新的列值对的字典
  • bulk（可选）：设置为True以进行批量更新
  • bulk_ids（可选）：当bulk=True时要更新的记录ID列表

示例：

# 根据ID更新单个记录
update_records(
    table_name="customers",
    row_id="123",
    data={"name": "John Smith", "status": "inactive"}
)

# 批量更新多个记录
update_records(
    table_name="customers",
    data={"status": "inactive"},  # 对所有记录应用相同的更新
    bulk=True,
    bulk_ids=["123", "456", "789"]
)

4. delete_records

从Nocodb表中删除一条或多条记录。

参数：

  • table_name：要从中删除的表名
  • row_id：要删除的记录ID（单个记录删除时必需）
  • bulk（可选）：设置为True以进行批量删除
  • bulk_ids（可选）：当bulk=True时要删除的记录ID列表

示例：

# 根据ID删除单个记录
delete_records(
    table_name="customers",
    row_id="123"
)

# 批量删除多个记录
delete_records(
    table_name="customers",
    bulk=True,
    bulk_ids=["123", "456", "789"]
)

5. get_schema

检索Nocodb表的架构（列）。

参数：

  • table_name：要获取其架构的表名

返回：

  • 包含表架构或错误信息的字典。架构详情通常嵌套在响应中，包括列列表。

示例：

# 获取“products”表的架构
get_schema(table_name="products")

关于Nocodb API的注意事项

此MCP服务器通过Nocodb API文档中描述的Nocodb v2 REST API进行交互。

关键实现细节：

  • 使用v2 API端点进行所有操作
  • 从NOCODB_BASE_ID环境变量获取基础ID
  • 自动解析表名对应的表ID
  • 通过xc-token头部处理身份验证（Nocodb v2 API的要求）
  • 提供全面的错误处理和响应

REST API参考：

身份验证

身份验证通过xc-token头部处理，该头部自动填充来自NOCODB_API_TOKEN环境变量。这是Nocodb v2 API所需的认证机制。

日志

服务器包含用于调试目的的日志。默认情况下，MCP服务器的日志级别在nocodb_mcp_server.py中设置为ERROR（mcp = FastMCP("Nocodb MCP Server", log_level="ERROR")），以避免在标准操作如mcp list期间产生过多输出。如果需要更详细的日志以进行故障排除，可以取消注释logging.basicConfig部分并调整级别（例如，level=logging.INFO或level=logging.DEBUG）。

错误处理

所有工具都返回结构化的响应，如果操作失败，则包含错误信息。这使得确定操作是否成功以及排查问题变得容易。

安全考虑

  • 使用专用API令牌，仅具有执行操作所需的最小权限。
  • 切勿在公共存储库或不安全的位置共享API令牌。
  • 通过Nocodb的权限系统限制数据库访问，仅限于必要的操作。
  • 启用日志和审计，以便在Nocodb实例中进行安全监控。
  • 定期审查和轮换API令牌，以最小化安全风险。
  • 安全地存储环境变量，尤其是在生产环境中。

安全最佳实践

为了安全设置：

  1. 在Nocodb中创建一个具有受限权限的专用API令牌。
  2. 避免硬编码凭据——始终使用环境变量。
  3. 在Nocodb中设置适当的表级权限，以限制访问。
  4. 如果可用，启用审计日志。
  5. 定期审查数据库访问，以防止未经授权的访问。

⚠️ 重要提示：配置API令牌和数据库访问时，请始终遵循最小权限原则。