🚀 Quickbase MCP 连接器
这是一个用于与 Quickbase JSON RESTful API 集成的 模型上下文协议 (MCP) 连接器。
免责声明：这是一个非官方的独立项目，与 Quickbase, Inc. 没有任何关联、赞助或背书。此连接器“按原样”提供，不提供任何形式的保证，并且 Quickbase 不提供支持。用户在使用此连接器时，有责任自行遵守所有适用的法律、法规和安全要求。
🚀 快速开始
对于那些只想使用 Claude 或 Claude Code 来尝试此连接器的用户：
- 安装依赖项并设置服务器：
# 运行设置脚本以安装所有依赖项
./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
- 与 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"
}
}
}
}
- 与 Claude Code 配合使用：
# 此单命令可同时注册并启动 MCP 服务器
claude mcp add quickbase node src/quickbase/server.js
现在你可以在 Claude 会话中使用 Quickbase 工具了！示例提示： "使用 quickbase 连接器列出我的 Quickbase 应用中的所有表。"
✨ 主要特性
面向用户
- AI 驱动的 Quickbase 访问：通过 Claude 直接与你的 Quickbase 数据进行交互。
- 数据管理：通过自然语言创建、查看和更新你的应用、表和记录。
- 文件处理：上传和下载记录的文件附件。
- 报告访问：运行你的 Quickbase 报告，并直接在聊天中获取结果。
- 大数据集支持：在查询大量记录时自动处理分页。
面向开发者
- 全面的 API 覆盖：访问 Quickbase API 的核心功能。
- 结构化响应：一致的响应格式，便于可靠解析。
- 批量操作：高效处理批量记录操作。
- 错误诊断：带有状态码和故障排除信息的详细错误消息。
📦 安装指南
- 克隆仓库：
git clone https://github.com/danielbushman/Quickbase-MCP-connector.git
cd Quickbase-MCP-connector
- 设置环境：
./setup.sh
- 配置你的 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 子句语法
- 身份验证失败
- 权限问题
- 网络连接问题
所有错误响应都包含有用的诊断信息，以帮助进行故障排除。
贡献
- 分叉仓库
- 创建功能分支
- 提交你的更改
- 推送到分支
- 创建拉取请求
📄 许可证
本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。