claude-collab-mcp 0.2.0
MCP server for async collaboration between two Claude users via shared project state
Requires Python: >=3.12
Keywords: anthropic, async, claude, collaboration, fastmcp, mcp

# claude-collab-mcp

MCP server for async collaboration between two Claude users via shared project state.

Two people using Claude (Claude Code, Claude Desktop, or any MCP-compatible client) can share live project context through a Supabase backend. No cloud hosting required.

## Installation

```bash
# Using uvx (recommended, no install needed)
uvx claude-collab-mcp

# Or install with pip
pip install claude-collab-mcp

# Or install with uv
uv pip install claude-collab-mcp
```

## Setup

### 1. Create a Supabase Project

1. Go to [supabase.com](https://supabase.com) and create a free project
2. Run the schema setup in your Supabase SQL editor (see [setup.sql](setup.sql))
3. Copy your project URL and anon key from Settings > API

### 2. Configure Environment Variables

Each user needs three environment variables:

```bash
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
COLLAB_USER=kelly  # or justin, or any identifier
```

### 3. Add to Your Claude Client

**Claude Code:**
```bash
claude mcp add claude-collab -s user -e SUPABASE_URL=https://... -e SUPABASE_KEY=... -e COLLAB_USER=kelly -- uvx claude-collab-mcp
```

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "claude-collab": {
      "command": "uvx",
      "args": ["claude-collab-mcp"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_KEY": "your-anon-key",
        "COLLAB_USER": "justin"
      }
    }
  }
}
```

## Tools

### Core Collaboration

| Tool | Purpose |
|------|---------|
| `get_project_state(project_name)` | Full snapshot: open tasks, handoffs, decisions, context |
| `update_task(project_name, title, ...)` | Create or update task (upsert by title) |
| `post_handoff(project_name, to_user, title, context)` | Async handoff with rich context |
| `get_handoffs(user?)` | Pending handoffs, auto-acknowledges yours |
| `log_decision(project_name, decision, rationale)` | Append-only decision record |
| `add_context(project_name, key, value)` | Upsert shared context entry |
| `get_activity(project_name, since_hours?)` | Activity feed since N hours ago |

### Project Context Sync

| Tool | Purpose |
|------|---------|
| `sync_project_brief(project_name, brief?)` | Push/pull portable project overview (goals, architecture, context) |
| `post_session_summary(project_name, summary, ...)` | Record what was accomplished (like /commit for collaborators) |

### Git Integration

| Tool | Purpose |
|------|---------|
| `log_git_activity(project_name, type, message, ...)` | Log commits, pushes, merges so collaborators see code changes |

### File References

| Tool | Purpose |
|------|---------|
| `add_file_reference(project_name, name, url, ...)` | Store links to external files (Google Drive, GitHub, Figma) |
| `get_file_references(project_name)` | Retrieve all shared file links |

## Usage Pattern

Add this to any shared project's CLAUDE.md:

```markdown
## On Session Start
Before beginning any work:
1. Call get_activity("project-name", 24) for recent changes
2. Call get_handoffs() for pending handoffs
3. Summarize what's new before proceeding
```

## How It Works

```
User A's Claude → spawns local MCP server (stdio) → reads/writes Supabase
User B's Claude → spawns local MCP server (stdio) → reads/writes Supabase
```

Same package on both machines. Same Supabase database. Projects are created automatically on first use.

## Requirements

- Python 3.12+
- Supabase account (free tier works)
- MCP-compatible Claude client

## License

MIT