Quickbase MCP 连接器

一个用于与 Quickbase JSON RESTful API 集成的 Model Context Protocol (MCP) 连接器。

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

概览

此连接器使用 Model Context Protocol (MCP)，使像 Claude 这样的 AI 助手能够与 Quickbase 的 API 进行交互。它支持广泛的操作来管理 Quickbase 中的应用程序、表、字段、记录、文件和报告。

特性

对于用户

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

对于开发者

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

先决条件

• Python 3.8 或更高版本
• Node.js 14 或更高版本
• Quickbase API 凭证（领域主机名、用户令牌和应用 ID）

安装

1. 克隆仓库：

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

1. 设置环境：

./setup.sh

1. 配置您的 Quickbase 凭证：

cp .env.example .env
# Edit .env with your credentials

快速开始

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

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

# Run the setup script to install all dependencies
./setup.sh

# Create a .env file with your Quickbase credentials
echo "QUICKBASE_REALM_HOST=your-realm.quickbase.com
QUICKBASE_USER_TOKEN=your_user_token_here
QUICKBASE_APP_ID=your_app_id_here" > .env

1. 使用 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"
      }
    }
  }
}

1. 使用 Claude Code：

# This single command both registers and starts the MCP server
claude mcp add quickbase node src/quickbase/server.js

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

可用工具类别

连接工具

• 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)
• FastField 表单操作 (manage_fast_field_form)

开发者与贡献者指南

手动启动 MCP 服务器

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

node src/quickbase/server.js

运行测试

本节主要针对希望验证其更改或运行测试套件的贡献者。

所有测试位于 tests/ 目录中。您可以使用测试运行器来运行特定测试或全部测试：

# Run all tests
python tests/run_tests.py --all

# Run specific tests
python tests/run_tests.py connection pagination file

# Run the comprehensive validation script
python tests/run_tests.py validate

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

# Test connection
python tests/test_connection.py

# Test file operations
python tests/test_file_operations.py

# Test pagination
python tests/test_pagination.py

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

环境变量

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

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

# For file operation testing
QUICKBASE_TABLE_ID=your_table_id_here
QUICKBASE_RECORD_ID=your_record_id_here
QUICKBASE_FILE_FIELD_ID=your_file_field_id_here

# MCP Server Settings (optional)
MCP_SERVER_PORT=3535

错误处理

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

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

常见错误场景

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

所有错误响应都包含有助于故障排除的诊断信息。

贡献

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

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件