BitScale MCP Server

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

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.

Tools

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"*

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.

"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.

"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.

"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.

License

MIT