Bitscale Ai

by featherflow

1 stars

339 downloads

Not rated

GitHub

Other

About

Bitscale Ai is an MCP server that connects a BitScale workspace to Claude Desktop, enabling users to manage and run data enrichment grids directly through Claude’s interface. It is intended for users who want to query their BitScale grids, run enrichment jobs, and inspect…

Details

Author: featherflow
GitHub stars: 1
Downloads: 339
Categories: Other

- List all grids with search and pagination, including column definitions.
- Get full schema, settings, and data sources for any grid.
- Retrieve a ready‑to‑use curl command and API contract for a grid.
- Run grids synchronously (results in ≤120 s) or asynchronously (get a request_id).
- Poll the status of an async or timed‑out grid run.
- Rotate the workspace API key (irreversible, invalidates current key).
- View workspace plan, credit balances, search limits, and member counts.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Bitscale Ai

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

Install uv (one‑time), then add the bitscale MCP server entry to your Claude Desktop configuration file (claude_desktop_config.json) with your BITSCALE_API_KEY. Restart Claude Desktop. Alternatively, add the server via the claude mcp add command for Claude Code.

`get_workspace_details`

Get details about the current BitScale workspace — plan info, credit balances, people/company search limits, and member counts. The workspace is identified automatically from the API key configured during MCP setup. No parameters needed. Returns: workspace id, name, plan (name, credits_included, billing_interval, next_billing_date, price), credits (total, used, remaining, plan_credits, rollover, topup), people_company_searches (limit, used, remaining), and members (total, owners, admins, editors).

`list_grids`

List all Grids in the workspace with their column definitions. Grids are spreadsheet-like tables in BitScale that hold data rows and enrichment/formula columns. Use this to discover available grids before running them. Args: search: Optional keyword to filter grids by name (case-insensitive substring match). Example: "leads" to find lead-related grids. page: Page number for pagination (1-based, default: 1). limit: Results per page (default: 20, max: 100). Returns: paginated list of grids, each with id, name, description, row_count, column_count, created_at, updated_at, and columns array. The columns array contains only runnable columns (type: enrichment, formula, or merge) with their id (column UUID), name, type, and dependencies. Use the grid id from the results to call get_grid_details or run_grid. Note: the column UUIDs here are used for output_columns in run_grid. The input labels for run_grid are separate human-readable keys derived from the grid's API data source configuration.

`get_grid_details`

Get full metadata for a specific Grid, including all column definitions, grid settings, and attached data sources. Use this to inspect a grid's schema before running it — especially to understand the grid's input labels and output column UUIDs needed for the run_grid tool. Args: grid_id: UUID of the grid. Found in the grid URL at app.bitscale.ai/grid/{gridId}, or from list_grids results. Returns: grid id, name, description, row_count, created_at, updated_at, settings (auto_run, auto_dedupe, visibility, dedupe_column_id), columns (all columns including text, enrichment, formula, merge types with their id/key and name), and sources (data sources with schedule info). NOTE on columns vs run_grid inputs: - The column 'id' values here are UUIDs — use these for the 'output_columns' parameter of run_grid to filter which outputs you want. - The 'inputs' parameter of run_grid uses human-readable LABELS (e.g. "company_name", "website"), NOT column UUIDs. These labels are derived from the API data source columns configured on the grid. You can find the exact input labels in the BitScale app under the grid's Data Source → BitScale API panel, or by inspecting the source column names.

`run_grid`

Run a BitScale Grid by appending a new row with the given inputs and triggering all column enrichments. This is the primary tool for executing BitScale workflows. It adds a row to the grid, runs all enrichment/formula/merge columns, and returns the enriched outputs. IMPORTANT — inputs vs output_columns use DIFFERENT key formats: - 'inputs' uses human-readable LABELS (e.g. "company_name", "website") — these are NOT UUIDs. The labels are derived from the source columns configured on the grid's BitScale API data source. You can find the exact labels in the BitScale app by clicking the Data Source column, selecting the BitScale API source, and looking at the input fields. - 'output_columns' uses column UUIDs from get_grid_details to filter which output columns to return. Before calling this, use get_grid_details to understand the grid schema. To discover the exact input labels, check the grid's API data source panel in the BitScale app, or look at the source column configuration. Args: grid_id: UUID of the grid to run. Found in grid URL or list_grids. inputs: Key-value map of input LABELS to their values. These are human-readable keys like "company_name", "website", "email" — NOT column UUIDs. Example: {"company_name": "Acme Corp", "website": "acme.com"} mode: Execution mode — "sync" (default) or "async". - sync: waits up to 120 seconds for completion, returns outputs directly. If still processing, returns a request_id to poll with get_run_status. - async: returns a request_id immediately. Poll get_run_status for results. output_columns: Optional list of column UUIDs to include in the response. Use the column 'id' values from get_grid_details. If omitted, all enriched columns are returned. source_id: Optional UUID of a specific BitScale API data source on the grid. If omitted, the first available source is used. Returns: - sync completed: {mode, status: "completed", outputs: {column_uuid: {value, name}}} - sync timeout or async: {mode, status: "running", request_id, poll_url} The outputs object keys are column UUIDs, each containing {value, name} where 'name' is the human-readable column display name. If status is "running", use get_run_status with the returned request_id to poll for completion (every 2-5 seconds).

`get_run_status`

Check the status of a previously triggered Grid run. Use this after run_grid returns a request_id (either from async mode or when sync mode times out after 120 seconds). Poll every 2-5 seconds until status is "completed" or "failed". Avoid polling more frequently as requests count toward the rate limit (5 req/sec per workspace). Args: request_id: The request_id UUID returned by run_grid. Returns: {mode, status, grid_id, outputs (when completed)}. Status is one of: "running", "completed", or "failed". When completed, outputs contains {column_id: {value, name}} for each enriched column.

`get_grid_curl`

Get a ready-to-use curl command and structured API contract for running a specific Grid. Call this BEFORE run_grid to discover the exact input fields required by the grid — no trial and error needed. This endpoint returns the derived required inputs (traced from column dependencies), the full run URL, request body shape, and a copy-paste- ready curl command. 💡 Recommended workflow: 1. Call get_grid_curl to discover the exact input fields. 2. Call run_grid with the returned inputs shape and real values. Args: grid_id: UUID of the grid. Found in the grid URL at app.bitscale.ai/grid/{gridId}, or from list_grids. output_columns: Optional comma-separated list of column key IDs to include in the run. When provided, required inputs are derived only from the dependencies of the specified columns. When omitted, inputs are derived from all runnable columns in the grid. Example: "col-uuid-1,col-uuid-2" Returns: grid_id, grid_name, run_url, method, headers, request_body (with mode, inputs shape, and optional output_columns), output_columns array (id, name, type for each requested column), and a curl string ready to copy-paste into a terminal (replace YOUR_WORKSPACE_API_KEY).

`rotate_api_key`

Generate a new workspace API key and immediately invalidate the current one. WARNING: This action is irreversible. The moment this succeeds, the key used to call it stops working. All integrations must be updated with the new key immediately, and this MCP server must be restarted with the new BITSCALE_API_KEY environment variable. Returns: {"api_key": "sk-live-newkey..."} — the new workspace API key.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

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

| 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 |
| get_grid_curl | Get a ready-to-use curl command and API contract for running a grid — call this first to discover required inputs |
| 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"

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

| Endpoint | Method | Tool |
|----------|--------|------|
| /workspace | GET | get_workspace_details |
| /grids | GET | list_grids |
| /grids/:gridId | GET | get_grid_details |
| /grids/:gridId/curl | GET | get_grid_curl |
| /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

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

get_workspace_details

list_grids

get_grid_details

run_grid

get_run_status

get_grid_curl

rotate_api_key

Claude Desktop / Cursor

McpServers

BitScale MCP Server

Setup

1. Install uv (one-time)

2. Add to Claude Desktop config

3. Restart Claude Desktop

Tools

Usage Examples

How Grid Runs Work

Input Labels vs Output Column UUIDs

Claude Code

API Reference

API Key Rotation

License

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀

`get_workspace_details`

`list_grids`

`get_grid_details`

`run_grid`

`get_run_status`

`get_grid_curl`

`rotate_api_key`

1. Install `uv` (one-time)