MCP Quickbase

🚀 Quickbase MCP Connector

A Model Context Protocol (MCP) connector for integrating with the Quickbase JSON RESTful API.

DISCLAIMER: This is an unofficial, independent project not affiliated with, sponsored, or endorsed by Quickbase, Inc. This connector is provided "as-is" without warranty of any kind and is not supported by Quickbase. Users are responsible for their own compliance with all applicable laws, regulations, and security requirements when using this connector.

🚀 Quick Start

For those who just want to try this connector with Claude or Claude Code:

1. Install dependencies and set up the server:

# 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

2. Using with Claude Desktop (recommended):

Create a config file for Claude Desktop that automatically starts the server. The configuration file location depends on your operating system:

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

Add the following configuration:

{
  "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. Using with Claude Code:

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

Now you can use Quickbase tools in your Claude session! Example prompt: "List all tables in my Quickbase app using the quickbase connector."

✨ Features

For Users

• AI-Powered Quickbase Access: Talk to your Quickbase data directly through Claude
• Data Management: Create, view, and update your apps, tables, and records through natural language
• File Handling: Upload and download file attachments to your records
• Report Access: Run your Quickbase reports and get the results directly in chat
• Large Dataset Support: Handles pagination automatically when querying large numbers of records

For Developers

• Comprehensive API Coverage: Access to core Quickbase API functionality
• Structured Responses: Consistent response formatting for reliable parsing
• Batch Operations: Efficient handling of bulk record operations
• Error Diagnostics: Detailed error messages with status codes and troubleshooting information

📦 Installation

1. Clone the repository:

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

2. Set up the environment:

./setup.sh

3. Configure your Quickbase credentials:

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

📚 Documentation

Overview

This connector uses the Model Context Protocol (MCP) to enable AI assistants like Claude to interact with Quickbase's API. It supports a wide range of operations for managing apps, tables, fields, records, files, and reports with Quickbase.

Available Tool Categories

Connection Tools

• test_connection: Verify your Quickbase API connection
• check_auth: Check authentication status and permissions

App Tools

• get_app: Get details about a specific app
• get_apps: List all available apps
• create_app, update_app: Create and update applications

Table Tools

• get_table, get_tables: Retrieve table information
• create_table, update_table: Create and update tables

Field Tools

• get_field, get_fields: Retrieve field information
• create_field, update_field: Create and update fields

Record Tools

• get_record, query_records: Retrieve record data
• create_record, update_record: Individual record operations
• bulk_create_records, bulk_update_records: Efficient batch operations

File Tools

• upload_file: Upload a file to a record field
• download_file: Download a file from a record field
• manage_attachments: High-level attachment management

Report Tools

• run_report: Execute Quickbase reports

Not implemented

The following operations are not implemented:

• Delete operations (delete_app, delete_table, delete_field, delete_record, bulk_delete_records, delete_file)
• User operations (get_user, get_current_user, get_user_roles, manage_users)
• Form operations (manage_forms)
• Dashboard operations (manage_dashboards)
• Pipelines operations (manage_pipelines)
• FastField Form operations (manage_fast_field_form)

For Developers & Contributors

Starting the MCP Server Manually

If you need to manually start the server (for development or debugging):

node src/quickbase/server.js

Running Tests

This section is primarily for contributors who want to verify their changes or run the test suite.

All tests are located in the tests/ directory. You can use the test runner to run specific tests or all 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

Individual test scripts can also be run directly:

# Test connection
python tests/test_connection.py

# Test file operations
python tests/test_file_operations.py

# Test pagination
python tests/test_pagination.py

For more information about tests, see tests/README.md.

Environment Variables

The following environment variables may need to be configured:

# 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

Error Handling

The connector provides comprehensive error handling with:

• Error type classification
• HTTP status codes
• Detailed error messages from Quickbase API
• Suggested solutions
• Parameter validation
• JSON data validation
• Proper handling of API request errors

Common Error Scenarios

• Missing required parameters
• Invalid JSON data format
• Non-existent table or field IDs
• Invalid WHERE clause syntax
• Authentication failures
• Permission issues
• Network connectivity problems

All error responses include helpful diagnostic information to assist with troubleshooting.

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📄 License

MIT License - see LICENSE file for details