# Claude Bridge MCP server

> A local-first message bus that enables independent coding agents on different machines to exchange ordered messages through named channels.

- Repository: https://github.com/constripacity/Claude-Bridge
- Page: https://hostedmcp.org/servers/constripacity/claude-bridge
- Transport: stdio
- Stars: 15
- License: MIT
- Latest version: 1.3.0

## Install

### Claude Code

```sh
claude mcp add --env 'CLAUDE_BRIDGE_AUTH_TOKEN=<YOUR_CLAUDE_BRIDGE_AUTH_TOKEN>' claude-bridge -- uvx claude-code-bridge
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "claude-bridge": {
      "command": "uvx",
      "args": [
        "claude-code-bridge"
      ],
      "env": {
        "CLAUDE_BRIDGE_AUTH_TOKEN": "<YOUR_CLAUDE_BRIDGE_AUTH_TOKEN>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "claude-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "claude-code-bridge"
      ],
      "env": {
        "CLAUDE_BRIDGE_AUTH_TOKEN": "<YOUR_CLAUDE_BRIDGE_AUTH_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"claude-bridge","type":"stdio","command":"uvx","args":["claude-code-bridge"],"env":{"CLAUDE_BRIDGE_AUTH_TOKEN":"<YOUR_CLAUDE_BRIDGE_AUTH_TOKEN>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "claude-bridge": {
      "command": "uvx",
      "args": [
        "claude-code-bridge"
      ],
      "env": {
        "CLAUDE_BRIDGE_AUTH_TOKEN": "<YOUR_CLAUDE_BRIDGE_AUTH_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add claude-bridge --env 'CLAUDE_BRIDGE_AUTH_TOKEN=<YOUR_CLAUDE_BRIDGE_AUTH_TOKEN>' -- uvx claude-code-bridge
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.claude-bridge]
command = "uvx"
args = ["claude-code-bridge"]

[mcp_servers.claude-bridge.env]
CLAUDE_BRIDGE_AUTH_TOKEN = "<YOUR_CLAUDE_BRIDGE_AUTH_TOKEN>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'CLAUDE_BRIDGE_AUTH_TOKEN=<YOUR_CLAUDE_BRIDGE_AUTH_TOKEN>' claude-bridge uvx -- claude-code-bridge
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "claude-bridge": {
      "command": "uvx",
      "args": [
        "claude-code-bridge"
      ],
      "env": {
        "CLAUDE_BRIDGE_AUTH_TOKEN": "<YOUR_CLAUDE_BRIDGE_AUTH_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `CLAUDE_BRIDGE_AUTH_TOKEN` | no | yes | Optional Bearer token for HTTP mode. As of 1.2.0, binding a non-loopback host requires this token together with an explicit trusted host (CLAUDE_BRIDGE_TRUSTED_HOSTS), unless --allow-unauthenticated-network is passed; loopback (stdio and localhost) does not require it. When set, all HTTP endpoints except /status require Authorization: Bearer <token>. Not used in stdio mode. |
| `CLAUDE_BRIDGE_DB` | no | no | SQLite database path (default: ./claude-bridge.db). Share the same path across HTTP and stdio instances to share state. |

## Tools (13)

- `bridge_send`: Publish a durable message. Use content for legacy text/JSON, or message for the versioned structured envelope. Supply idempotency_key when a retry must not create a duplicate.
- `bridge_receive`: Read durable messages. Pass since_id for an explicit cursor or consumer_id to resume from that consumer's last acknowledged message. (read-only)
- `bridge_wait`: Wait efficiently for new messages after since_id or a durable consumer cursor. Use this instead of repeated polling; timeout is capped at 55 seconds. (read-only)
- `bridge_ack`: Acknowledge a message for a named consumer. The durable cursor advances monotonically and is scoped to this channel.
- `bridge_channels`: List all active channels and their message counts. (read-only)
- `bridge_ping`: Check if the bridge server is alive and get a status summary. (read-only)
- `bridge_clear`: Clear all messages from a specific channel. Useful for resetting state.
- `bridge_status`: Get the last N messages from ALL channels at once. Useful for getting a full picture of what's happening across agents. (read-only)
- `bridge_enqueue`: Add a task to a channel's work queue for a worker to claim. Give payload (structured JSON) or content (a string). Pass idempotency_key so a retried enqueue does not create a duplicate.
- `bridge_claim`: Atomically claim the next task from a channel's queue — no two workers ever get the same task. The claim holds a lease for lease_seconds; complete or fail it before the lease expires or it is requeued to another worker. Set wait_seconds to long-poll.
- `bridge_complete`: Mark a claimed task completed. Requires the lease_token returned by bridge_claim; a task whose lease expired and was reclaimed cannot be completed by the previous holder.
- `bridge_fail`: Mark a claimed task failed. By default it is requeued (after retry_delay_seconds) until max_attempts is exhausted, then dead-lettered; set requeue=false to dead-letter immediately. Requires the lease_token from bridge_claim.
- `bridge_tasks`: Inspect a channel's task queue: per-status counts plus a recent task list. Read-only. (read-only)

## FAQ

### Does Claude Bridge call model APIs?

No, it is a transport layer and does not call any model APIs itself.

### How can I secure a cross-machine deployment?

You should provide a trusted host using the --trusted-host flag and require a Bearer token for authentication.

### Can I use Claude Bridge to distribute work among multiple agents?

Yes, it includes a task queue feature where a fleet of worker agents can share work without double-processing tasks.

### What happens if a worker agent crashes while processing a task?

If the lease expires without the task being resolved, the task is automatically requeued or dead-lettered.
