BitScale MCP Server

Connect your BitScale workspace to Claude via the Model Context Protocol (MCP).

Tools

How Grid Runs Work

1. Discover grids — call list_grids to find available grids and their IDs.
2. Get the API contract — call get_grid_curl with the grid ID to get the exact input fields required, a shaped request body, and a copy-paste curl command. This is the recommended way to understand what a grid needs before running it.
3. Run the grid — call run_grid with the grid ID and an inputs map of human-readable labels to values (as returned by get_grid_curl). In sync mode (default), results return directly within 120 seconds. In async mode, you get a request_id to poll.
4. Poll if needed — if the run is still processing, call get_run_status with the request_id every 2-5 seconds until status is completed.

Input Labels vs Output Column UUIDs

This is an important distinction when using run_grid:

• inputs — uses human-readable labels like "company_name", "website", "email". These labels are derived from the source columns configured on the grid's BitScale API data source. They are not column UUIDs. You can find the exact labels in the BitScale app by clicking the Data Source column → BitScale API source.

  Copy

  "inputs": {
    "company_name": "Acme Corp",
    "website": "acme.com"
  }

• output_columns — uses column UUIDs from get_grid_details to filter which enriched columns appear in the response.

  Copy

  "output_columns": [
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
  ]

• Response outputs — keyed by column UUIDs, each containing {value, name} where name is the human-readable display name.

  Copy

  "outputs": {
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8": {
      "value": "AI-powered data enrichment platform",
      "name": "Company Description"
    }
  }

Claude Code

claude mcp add bitscale \
  --command uvx \
  --args bitscale-mcp \
  --env BITSCALE_API_KEY=your_api_key_here

API Reference

Requests hit https://api.bitscale.ai/api/v1, authenticated via X-API-KEY header. Default rate limit: 5 req/s per workspace.

API Key Rotation

Calling rotate_api_key immediately invalidates the current key and returns a new one. Update BITSCALE_API_KEY in your config and restart Claude Desktop after rotating.

Setup

1. Install uv (one-time)

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
OR 
brew install uv

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Add to Claude Desktop config

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

{
  "mcpServers": {
    "bitscale": {
      "command": "uvx",
      "args": ["bitscale-mcp"],
      "env": {
        "BITSCALE_API_KEY": "your_api_key_here"
      }
    }
  }
}

3. Restart Claude Desktop

That's it. No cloning, no pip install — uvx pulls and runs the package automatically.

Usage Examples

"List all my BitScale grids"

"Show me the details of the Lead Enrichment grid"

"Get the curl command for the Lead Enrichment grid"

"Run the Lead Enrichment grid with company_name 'Acme Corp' and website 'acme.com'"

"Find phone numbers for people at Stripe using my BitScale grid"

"Check the status of run 550e8400-e29b-41d4-a716-446655440000"

License

MIT