Quickbase MCP Server

🚀 QuickBase MCP Server

QuickBase MCP Server 是一个模型上下文协议（MCP）服务器，为 QuickBase 操作提供了极大的灵活性。该服务器允许你通过 MCP 工具创建表、添加字段、修改关系，并执行所有 QuickBase 操作。

🚀 快速开始

获取 QuickBase 用户令牌

1. 访问 QuickBase → 我的应用 → 用户账户。
2. 点击“管理用户令牌”。
3. 点击“新建用户令牌”。
4. 为其命名，例如“MCP Server”。
5. 设置适当的权限。
6. 将令牌复制到你的 .env 文件中。

安装

1. 克隆并设置服务器：

cd quickbase-mcp-server
npm install

2. 复制环境配置：

cp env.example .env

3. 在 .env 文件中配置你的 QuickBase 凭证：

# QuickBase 配置
QB_REALM=yourname.quickbase.com
QB_USER_TOKEN=your_quickbase_user_token_here
QB_APP_ID=yourid

# 可选：默认设置
QB_DEFAULT_TIMEOUT=30000
QB_MAX_RETRIES=3

# MCP 服务器配置
MCP_SERVER_NAME=quickbase-mcp
MCP_SERVER_VERSION=1.0.0

4. 构建项目：

npm run build

使用

独立运行服务器：

npm start

添加到你的 MCP 客户端配置：

添加到你的 MCP 客户端配置（例如，Claude Desktop）：

{
  "mcpServers": {
    "quickbase": {
      "command": "node",
      "args": ["/path/to/quickbase-mcp-server/dist/index.js"],
      "env": {
        "QB_REALM": "yourname.quickbase.com",
        "QB_USER_TOKEN": "your_token_here",
        "QB_APP_ID": "yourid"
      }
    }
  }
}

✨ 主要特性

应用管理

• 获取应用信息
• 列出所有表
• 测试连接

表操作

• 创建新表
• 获取表信息
• 更新表属性
• 删除表

字段管理

• 获取表的所有字段
• 创建新字段（支持所有类型）
• 更新现有字段
• 删除字段
• 支持查找、公式、关系

记录操作

• 带过滤和排序的查询记录
• 获取特定记录
• 创建单条或多条记录
• 更新现有记录
• 删除记录
• 按文本搜索记录
• 批量操作

关系管理

• 创建父子关系
• 获取现有关系
• 外键管理

实用功能

• 获取并运行报告
• 高级查询功能
• 错误处理和重试逻辑

📦 安装指南

克隆并设置服务器

cd quickbase-mcp-server
npm install

复制环境配置

cp env.example .env

配置 QuickBase 凭证

在 .env 文件中配置你的 QuickBase 凭证：

# QuickBase 配置
QB_REALM=yourname.quickbase.com
QB_USER_TOKEN=your_quickbase_user_token_here
QB_APP_ID=yourid

# 可选：默认设置
QB_DEFAULT_TIMEOUT=30000
QB_MAX_RETRIES=3

# MCP 服务器配置
MCP_SERVER_NAME=quickbase-mcp
MCP_SERVER_VERSION=1.0.0

构建项目

npm run build

💻 使用示例

基础用法

创建新表

{
  "name": "quickbase_create_table",
  "arguments": {
    "name": "New Projects",
    "description": "Project tracking table"
  }
}

向表中添加字段

{
  "name": "quickbase_create_field",
  "arguments": {
    "tableId": "bu65pc8px",
    "label": "Project Status",
    "fieldType": "text_choice",
    "choices": ["Planning", "Active", "Complete", "On Hold"],
    "required": true
  }
}

带过滤的查询记录

{
  "name": "quickbase_query_records",
  "arguments": {
    "tableId": "bu65pc8px",
    "where": "{6.EX.'John'}",
    "top": 10,
    "sortBy": [{"fieldId": 3, "order": "DESC"}]
  }
}

创建新记录

{
  "name": "quickbase_create_record",
  "arguments": {
    "tableId": "bu65pc8px",
    "fields": {
      "6": {"value": "John Doe"},
      "7": {"value": "123 Main St"},
      "8": {"value": "john@example.com"}
    }
  }
}

高级用法

目前暂无高级用法示例。

📚 详细文档

可用工具

应用工具

• quickbase_get_app_info - 获取应用信息
• quickbase_get_tables - 列出所有表
• quickbase_test_connection - 测试连接

表工具

• quickbase_create_table - 创建新表
• quickbase_get_table_info - 获取表详情
• quickbase_delete_table - 删除表

字段工具

• quickbase_get_table_fields - 获取所有字段
• quickbase_create_field - 创建新字段
• quickbase_update_field - 更新现有字段
• quickbase_delete_field - 删除字段

记录工具

• quickbase_query_records - 带过滤/排序的查询
• quickbase_get_record - 获取特定记录
• quickbase_create_record - 创建新记录
• quickbase_update_record - 更新现有记录
• quickbase_delete_record - 删除记录
• quickbase_bulk_create_records - 创建多条记录
• quickbase_search_records - 按文本搜索

关系工具

• quickbase_create_relationship - 创建表关系
• quickbase_get_relationships - 获取现有关系

实用工具

• quickbase_get_reports - 获取所有报告
• quickbase_run_report - 运行特定报告

支持的字段类型

• text - 单行文本
• text_choice - 单选下拉框
• text_multiline - 多行文本
• richtext - 富文本编辑器
• numeric - 数字字段
• currency - 货币字段
• percent - 百分比字段
• date - 日期字段
• datetime - 日期/时间字段
• checkbox - 复选框字段
• email - 电子邮件字段
• phone - 电话号码字段
• url - URL 字段
• address - 地址字段
• file - 文件附件
• lookup - 从另一个表查找
• formula - 计算字段
• reference - 表引用

开发

以开发模式运行

npm run dev

运行测试

npm test

故障排除

常见问题

1. 身份验证错误
   • 检查你的用户令牌是否正确。
   • 验证令牌权限是否包含你的应用。
   • 确保领域主机名正确。
2. 未找到表/字段
   • 验证表/字段 ID 是否正确。
   • 检查你是否有访问权限。
3. 字段创建失败
   • 检查字段类型是否受支持。
   • 验证选择字段是否提供了选项。
   • 确保公式字段的公式语法正确。

启用调试日志

设置环境变量：

DEBUG=quickbase-mcp:*

🔧 技术细节

本服务器通过以下方式为 QuickBase 操作提供了极大的灵活性：

1. 直接 API 访问 - 直接使用 QuickBase REST API v1。
2. 完整的字段支持 - 支持所有 QuickBase 字段类型。
3. 关系管理 - 可以创建和管理表关系。
4. 批量操作 - 高效的批量记录操作。
5. 高级查询 - 支持完整的 QuickBase 查询语法。
6. 错误处理 - 全面的错误处理和重试逻辑。

📄 许可证

本项目采用 MIT 许可证。