bitscale-mcp 0.1.1

MCP server for BitScale — connect your BitScale workspace to Claude

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

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

Tool	Description
get_workspace_details	Get workspace plan, credit balances, search limits, and member counts
list_grids	List all grids with optional search & pagination, returns column definitions
get_grid_details	Get a grid's full schema — columns, settings, and data sources
run_grid	Run a grid by providing input values, supports sync and async modes
get_run_status	Poll the status of an async or timed-out grid run by request_id
rotate_api_key	Rotate the workspace API key (irreversible, invalidates current key)

---

Usage Examples

"List all my BitScale grids"

"Show me the details of 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. Inspect the grid — call get_grid_details with the grid ID to see column definitions. Text-type columns are inputs; enrichment/formula/merge columns produce outputs.
3. Run the grid — call run_grid with the grid ID and an inputs map of column keys to values. 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.

---

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.

Endpoint	Method	Tool
/workspace	GET	get_workspace_details
/grids	GET	list_grids
/grids/:gridId	GET	get_grid_details
/grids/:gridId/run	POST	run_grid
/run/status/:requestId	GET	get_run_status
/api-key/rotate	POST	rotate_api_key

---

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