MCP Quickbase

🚀 Quickbase MCP 连接器

这是一个用于与 Quickbase JSON RESTful API 集成的 模型上下文协议 (MCP) 连接器。

免责声明：这是一个非官方的独立项目，与 Quickbase, Inc. 没有任何关联、赞助或背书。此连接器“按原样”提供，不提供任何形式的保证，并且 Quickbase 不提供支持。用户在使用此连接器时，有责任自行遵守所有适用的法律、法规和安全要求。

🚀 快速开始

对于那些只想使用 Claude 或 Claude Code 来尝试此连接器的用户：

1. 安装依赖项并设置服务器：

# 运行设置脚本以安装所有依赖项
./setup.sh

# 创建一个包含 Quickbase 凭证的 .env 文件
echo "QUICKBASE_REALM_HOST=your-realm.quickbase.com
QUICKBASE_USER_TOKEN=your_user_token_here
QUICKBASE_APP_ID=your_app_id_here" > .env

2. 与 Claude Desktop 配合使用（推荐）：

为 Claude Desktop 创建一个配置文件，该文件可自动启动服务器。配置文件的位置取决于你的操作系统：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "quickbase": {
      "command": "/path/to/node",
      "args": [
        "/path/to/Quickbase-MCP-connector/src/quickbase/server.js"
      ],
      "env": {
        "QUICKBASE_REALM": "your-realm",
        "QUICKBASE_USER_TOKEN": "your-user-token",
        "QUICKBASE_APP_ID": "your-app-id"
      }
    }
  }
}

3. 与 Claude Code 配合使用：

# 此单命令可同时注册并启动 MCP 服务器
claude mcp add quickbase node src/quickbase/server.js

现在你可以在 Claude 会话中使用 Quickbase 工具了！示例提示： "使用 quickbase 连接器列出我的 Quickbase 应用中的所有表。"

✨ 主要特性

面向用户

• AI 驱动的 Quickbase 访问：通过 Claude 直接与你的 Quickbase 数据进行交互。
• 数据管理：通过自然语言创建、查看和更新你的应用、表和记录。
• 文件处理：上传和下载记录的文件附件。
• 报告访问：运行你的 Quickbase 报告，并直接在聊天中获取结果。
• 大数据集支持：在查询大量记录时自动处理分页。

面向开发者

• 全面的 API 覆盖：访问 Quickbase API 的核心功能。
• 结构化响应：一致的响应格式，便于可靠解析。
• 批量操作：高效处理批量记录操作。
• 错误诊断：带有状态码和故障排除信息的详细错误消息。

📦 安装指南

1. 克隆仓库：

git clone https://github.com/danielbushman/Quickbase-MCP-connector.git
cd Quickbase-MCP-connector

2. 设置环境：

./setup.sh

3. 配置你的 Quickbase 凭证：

cp .env.example .env
# 使用你的凭证编辑 .env

📚 详细文档

可用工具类别

连接工具

• test_connection：验证你的 Quickbase API 连接。
• check_auth：检查身份验证状态和权限。

应用工具

• get_app：获取特定应用的详细信息。
• get_apps：列出所有可用的应用。
• create_app, update_app：创建和更新应用程序。

表工具

• get_table, get_tables：检索表信息。
• create_table, update_table：创建和更新表。

字段工具

• get_field, get_fields：检索字段信息。
• create_field, update_field：创建和更新字段。

记录工具

• get_record, query_records：检索记录数据。
• create_record, update_record：单个记录操作。
• bulk_create_records, bulk_update_records：高效的批量操作。

文件工具

• upload_file：将文件上传到记录字段。
• download_file：从记录字段下载文件。
• manage_attachments：高级附件管理。

报告工具

• run_report：执行 Quickbase 报告。

未实现的操作

以下操作尚未实现：

• 删除操作（delete_app、delete_table、delete_field、delete_record、bulk_delete_records、delete_file）
• 用户操作（get_user、get_current_user、get_user_roles、manage_users）
• 表单操作（manage_forms）
• 仪表盘操作（manage_dashboards）
• 管道操作（manage_pipelines）
• 快速字段表单操作（manage_fast_field_form）

面向开发者和贡献者

手动启动 MCP 服务器

如果你需要手动启动服务器（用于开发或调试）：

node src/quickbase/server.js

运行测试

此部分主要面向想要验证其更改或运行测试套件的贡献者。

所有测试都位于 tests/ 目录中。你可以使用测试运行器运行特定测试或所有测试：

# 运行所有测试
python tests/run_tests.py --all

# 运行特定测试
python tests/run_tests.py connection pagination file

# 运行综合验证脚本
python tests/run_tests.py validate

也可以直接运行单个测试脚本：

# 测试连接
python tests/test_connection.py

# 测试文件操作
python tests/test_file_operations.py

# 测试分页
python tests/test_pagination.py

有关测试的更多信息，请参阅 tests/README.md。

环境变量

可能需要配置以下环境变量：

# Quickbase API 凭证
QUICKBASE_REALM_HOST=your-realm.quickbase.com
QUICKBASE_USER_TOKEN=your_user_token_here
QUICKBASE_APP_ID=your_app_id_here

# 用于文件操作测试
QUICKBASE_TABLE_ID=your_table_id_here
QUICKBASE_RECORD_ID=your_record_id_here
QUICKBASE_FILE_FIELD_ID=your_file_field_id_here

# MCP 服务器设置（可选）
MCP_SERVER_PORT=3535

错误处理

该连接器提供了全面的错误处理，包括：

• 错误类型分类
• HTTP 状态码
• Quickbase API 的详细错误消息
• 建议的解决方案
• 参数验证
• JSON 数据验证
• 正确处理 API 请求错误

常见错误场景

• 缺少必需参数
• 无效的 JSON 数据格式
• 不存在的表或字段 ID
• 无效的 WHERE 子句语法
• 身份验证失败
• 权限问题
• 网络连接问题

所有错误响应都包含有用的诊断信息，以帮助进行故障排除。

贡献

1. 分叉仓库
2. 创建功能分支
3. 提交你的更改
4. 推送到分支
5. 创建拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。