@ballast-sh/bridge

MCP bridge connecting Claude Desktop to Ballast collections.

Installation

npm install -g @ballast-sh/bridge

Or use with npx (no installation required):

npx @ballast-sh/bridge --collection your-collection-name

Usage

Claude Desktop Configuration

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ballast": {
      "command": "npx",
      "args": ["-y", "@ballast-sh/bridge", "--collection", "your-collection-name"],
      "env": {
        "BALLAST_API_KEY": "your-api-key-here"
      }
    }
  }
}

For custom Ballast deployment:

{
  "mcpServers": {
    "ballast": {
      "command": "npx",
      "args": [
        "-y", 
        "@ballast-sh/bridge", 
        "--collection", "your-collection-name",
        "--base-url", "https://your-ballast-instance.com"
      ],
      "env": {
        "BALLAST_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop

After updating the config, restart Claude Desktop to load the MCP server.

Available Tools

Once connected, Claude can use these tools:

• search: Search through your Ballast collection
• list_sources: List all data sources in the collection
• trigger_sync: Trigger a data sync
• get_collection_info: Get collection information

Development

# Clone and install
git clone <repo>
cd bridge
npm install

# Build
npm run build

# Test locally
node dist/index.js --collection test-collection

Environment Variables

• BALLAST_API_KEY (required): Your Ballast API key

Command Line Options

• --collection <n> (required): Collection name
• --base-url <url>: Ballast base URL (default: http://localhost:5173)

Example Usage in Claude

Once configured, you can ask Claude:

"Search my marketing-db collection for recent data"

"List all data sources in my Ballast collection"

"Trigger a sync for my collection"

License

MIT