LawrenceCirillo/QuickBase-MCP-Server

QuickBase MCP Server

A Model Context Protocol (MCP) server that provides maximum flexibility for QuickBase operations. This server allows you to create tables, add fields, modify relationships, and perform all QuickBase operations through MCP tools.

Features

Application Management

• Get application information
• List all tables
• Test connection

Table Operations

• Create new tables
• Get table information
• Update table properties
• Delete tables

Field Management

• Get all fields for a table
• Create new fields (all types supported)
• Update existing fields
• Delete fields
• Support for lookups, formulas, relationships

Record Operations

• Query records with filtering and sorting
• Get specific records
• Create single or multiple records
• Update existing records
• Delete records
• Search records by text
• Bulk operations

Relationship Management

• Create parent-child relationships
• Get existing relationships
• Foreign key management

Utility Functions

• Get and run reports
• Advanced querying capabilities
• Error handling and retry logic

Installation

1. Clone and setup the server:

cd quickbase-mcp-server
npm install

2. Copy environment configuration:

cp env.example .env

3. Configure your QuickBase credentials in .env:

# QuickBase Configuration
QB_REALM=yourname.quickbase.com
QB_USER_TOKEN=your_quickbase_user_token_here
QB_APP_ID=yourid

# Optional: Default settings
QB_DEFAULT_TIMEOUT=30000
QB_MAX_RETRIES=3

# MCP Server Configuration
MCP_SERVER_NAME=quickbase-mcp
MCP_SERVER_VERSION=1.0.0

4. Build the project:

npm run build

Getting Your QuickBase User Token

1. Go to QuickBase → My Apps → User Account
2. Click "Manage user tokens"
3. Click "New user token"
4. Give it a name like "MCP Server"
5. Set appropriate permissions
6. Copy the token to your .env file

Usage

Run the server standalone:

npm start

Add to your MCP client configuration:

Add to your MCP client configuration (e.g., 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"
      }
    }
  }
}

Available Tools

Application Tools

• quickbase_get_app_info - Get application information
• quickbase_get_tables - List all tables
• quickbase_test_connection - Test connection

Table Tools

• quickbase_create_table - Create new table
• quickbase_get_table_info - Get table details
• quickbase_delete_table - Delete table

Field Tools

• quickbase_get_table_fields - Get all fields
• quickbase_create_field - Create new field
• quickbase_update_field - Update existing field
• quickbase_delete_field - Delete field

Record Tools

• quickbase_query_records - Query with filters/sorting
• quickbase_get_record - Get specific record
• quickbase_create_record - Create new record
• quickbase_update_record - Update existing record
• quickbase_delete_record - Delete record
• quickbase_bulk_create_records - Create multiple records
• quickbase_search_records - Search by text

Relationship Tools

• quickbase_create_relationship - Create table relationship
• quickbase_get_relationships - Get existing relationships

Utility Tools

• quickbase_get_reports - Get all reports
• quickbase_run_report - Run specific report

Example Usage

Create a new table:

{
  "name": "quickbase_create_table",
  "arguments": {
    "name": "New Projects",
    "description": "Project tracking table"
  }
}

Add a field to a table:

{
  "name": "quickbase_create_field",
  "arguments": {
    "tableId": "bu65pc8px",
    "label": "Project Status",
    "fieldType": "text_choice",
    "choices": ["Planning", "Active", "Complete", "On Hold"],
    "required": true
  }
}

Query records with filtering:

{
  "name": "quickbase_query_records",
  "arguments": {
    "tableId": "bu65pc8px",
    "where": "{6.EX.'John'}",
    "top": 10,
    "sortBy": [{"fieldId": 3, "order": "DESC"}]
  }
}

Create a new record:

{
  "name": "quickbase_create_record",
  "arguments": {
    "tableId": "bu65pc8px",
    "fields": {
      "6": {"value": "John Doe"},
      "7": {"value": "123 Main St"},
      "8": {"value": "john@example.com"}
    }
  }
}

Field Types Supported

• text - Single line text
• text_choice - Single choice dropdown
• text_multiline - Multi-line text
• richtext - Rich text editor
• numeric - Number field
• currency - Currency field
• percent - Percentage field
• date - Date field
• datetime - Date/time field
• checkbox - Checkbox field
• email - Email field
• phone - Phone number field
• url - URL field
• address - Address field
• file - File attachment
• lookup - Lookup from another table
• formula - Calculated field
• reference - Table reference

Development

Run in development mode:

npm run dev

Run tests:

npm test

Troubleshooting

Common Issues

1. Authentication Error

   • Check your user token is correct
   • Verify token permissions include your app
   • Ensure realm hostname is correct

2. Table/Field Not Found

   • Verify table/field IDs are correct
   • Check if you have permissions to access

3. Field Creation Fails

   • Check field type is supported
   • Verify choices are provided for choice fields
   • Ensure formula syntax is correct for formula fields

Enable Debug Logging

Set environment variable:

DEBUG=quickbase-mcp:*

Implementation Notes

This server provides the maximum flexibility for QuickBase operations by:

1. Direct API Access - Uses QuickBase REST API v1 directly
2. Complete Field Support - Supports all QuickBase field types
3. Relationship Management - Can create and manage table relationships
4. Bulk Operations - Efficient bulk record operations
5. Advanced Querying - Full QuickBase query syntax support
6. Error Handling - Comprehensive error handling and retry logic

License

MIT License