JinDaGe - QuickBase-MCP-Server MCP Details

article

README

🚀 QuickBase MCP Server

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

🚀 快速开始

获取 QuickBase 用户令牌

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

安装

克隆并设置服务器：

cd quickbase-mcp-server
npm install

复制环境配置：

cp env.example .env

在 .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

使用

独立运行服务器：

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

故障排除

常见问题

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

启用调试日志

设置环境变量：

DEBUG=quickbase-mcp:*

🔧 技术细节

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

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

📄 许可证

本项目采用 MIT 许可证。