# Overboard Studio — MCP Server

[Overboard Studio](https://overboard.studio) is a collaborative whiteboard. This is the official Model Context Protocol (MCP) server: it lets any AI agent (Claude, ChatGPT, Cursor, Codex, …) create and manage real, shareable boards — sticky notes, shapes, text, frames, charts, flowcharts, tables, connectors — that show up live in the Overboard web app.

**Hosted endpoint (recommended):** `https://overboard.studio/mcp` (OAuth, supports Claude.ai, ChatGPT, Cursor, etc.)

**Stdio mode:** for Claude Code / Cursor / Claude Desktop running locally.

## Quick connect

### Claude.ai (web)
Settings → Connectors → Add custom connector → URL: `https://overboard.studio/mcp` → complete the OAuth flow.

### Claude Code
```bash
claude mcp add --transport http overboard https://overboard.studio/mcp
/mcp auth
```

### Claude Desktop (stdio)
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "overboard": {
      "command": "npx",
      "args": ["-y", "@overboard/mcp-server"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}
```

### Cursor
Add to `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "overboard": {
      "url": "https://overboard.studio/mcp"
    }
  }
}
```

## Tools (16)

### Boards
| Tool | Description | Annotation |
|------|-------------|------------|
| `get_current_user` | Authenticated user's id, email, display name | read-only |
| `list_boards` | Boards you own or were invited to | read-only |
| `get_board` | Board metadata + member/element counts | read-only |
| `create_board` | New empty board, you become owner | write |
| `create_board_with_elements` | New board pre-populated with elements (preferred) | write |
| `rename_board` | Rename a board you own | write, idempotent |
| `delete_board` | Cascade-delete board, members, elements | **destructive** |
| `get_board_url` | Direct URL to open board in the web app | read-only |

### Elements
| Tool | Description | Annotation |
|------|-------------|------------|
| `get_elements` | All elements on a board | read-only |
| `create_element` | Add sticky note / shape / text / frame / chart / etc. | write |
| `bulk_create_elements` | Batch create (preferred for >2 elements) | write |
| `update_element` | Merge properties — move/resize/recolor/edit text | write, idempotent |
| `delete_element` | Remove a single element | **destructive** |

### Collaboration
| Tool | Description | Annotation |
|------|-------------|------------|
| `get_collaborators` | Members of a board with roles | read-only |
| `get_board_activity` | Recent element changes (default last 24h) | read-only |
| `invite_to_board` | Generate a shareable invitation link | write |

## Element types

`sticky-note`, `text`, `path`, `shape`, `connector`, `frame`, `graph`, `chart`, `flowchart`, `table`, `timeline`, `kanban`, `doc`, `vote`, `timer`, `estimation`

Smart defaults are applied for position, size, and styling — you only need to specify what you want to customize.

## Authentication

The hosted endpoint uses **OAuth 2.0**. The client (Claude.ai, etc.) walks the user through Overboard's auth flow once; tokens are valid for 30 days.

Stdio mode uses the Supabase service-role key — pass it as an env var. Each tool call enforces per-user board access via Supabase Row-Level Security; the service-role key only bypasses RLS for the tools that need to read/write multi-user state.

## Build from source

```bash
npm install
npm run build
node dist/index.js
```

For HTTP mode:
```bash
node dist/index.js --http --port=3002
```

## Test with MCP Inspector

```bash
SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... \
  npx @modelcontextprotocol/inspector node dist/index.js
```

## Example prompts

Once connected, try:

- *"List all my boards"*
- *"Create a sprint planning board with 5 yellow sticky notes for: Design login, Set up API, Write tests, Deploy staging, Code review"*
- *"Show me everything on board {id}"*
- *"Move the first sticky note to (500, 300) and recolor it green"*
- *"Generate an invite link for board {id} as editor"*

## License

MIT