# basecamp-mcp

MCP (Model Context Protocol) server for [Basecamp CLI](https://github.com/basecamp/basecamp-cli).

Exposes Basecamp commands as MCP tools over HTTP or stdio. Shells out to the
`basecamp` CLI binary, so all auth, config, and output formatting is handled
by the CLI.

## Prerequisites

- [Basecamp CLI](https://github.com/basecamp/basecamp-cli) installed and authenticated (`basecamp auth login`)
- Python 3.11+ / [uv](https://docs.astral.sh/uv/)

## Quick Start

One command to start the server:

```bash
uvx --from "git+https://github.com/FarisHijazi/basecamp-mcp.git" basecamp-mcp --port 8818
```

Then add it to Claude Code:

```bash
claude mcp add --transport http basecamp http://localhost:8818/mcp --scope user
```

That's it. Start a new Claude Code session and you'll have all 49 Basecamp tools available.

## Claude Code MCP Config

If you prefer to configure manually, add this to your `.mcp.json` (project-level) or `~/.claude.json` (global):

**HTTP mode** (run the server yourself):
```json
{
  "mcpServers": {
    "basecamp": {
      "type": "url",
      "url": "http://localhost:8818/mcp"
    }
  }
}
```

**Stdio mode** (Claude Code spawns the process automatically):
```json
{
  "mcpServers": {
    "basecamp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/FarisHijazi/basecamp-mcp.git",
        "basecamp-mcp", "--stdio"
      ]
    }
  }
}
```

## Usage

```bash
# Run from GitHub (no install needed)
uvx --from "git+https://github.com/FarisHijazi/basecamp-mcp.git" basecamp-mcp --port 8818

# Or install locally
uv pip install -e .
basecamp-mcp --port 8818

# Stdio transport (for local Claude Code)
basecamp-mcp --stdio
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `BASECAMP_BINARY` | `basecamp` | Path to the basecamp CLI binary |

## Available Tools (49)

All tools shell out to `basecamp --agent <command> [args]`.

| Tool | CLI Equivalent |
|---|---|
| `basecamp_projects_list` | `basecamp projects list` |
| `basecamp_projects_show` | `basecamp projects show` |
| `basecamp_projects_create` | `basecamp projects create` |
| `basecamp_todos_list` | `basecamp todos list` |
| `basecamp_todos_create` | `basecamp todos create` |
| `basecamp_todos_complete` | `basecamp todos complete` |
| `basecamp_todos_update` | `basecamp todos update` |
| `basecamp_todolists_list` | `basecamp todolists list` |
| `basecamp_messages_list` | `basecamp messages list` |
| `basecamp_messages_create` | `basecamp messages create` |
| `basecamp_comments_create` | `basecamp comments create` |
| `basecamp_chat_post` | `basecamp chat post` |
| `basecamp_cards_list` | `basecamp cards list` |
| `basecamp_cards_move` | `basecamp cards move` |
| `basecamp_files_list` | `basecamp files list` |
| `basecamp_schedule_entries` | `basecamp schedule entries` |
| `basecamp_people_list` | `basecamp people list` |
| `basecamp_search` | `basecamp search` |
| `basecamp_show` | `basecamp show` |
| `basecamp_me` | `basecamp me` |
| `basecamp_accounts_list` | `basecamp accounts list` |
| `basecamp_notifications_list` | `basecamp notifications list` |
| `basecamp_reports_assigned` | `basecamp reports assigned` |
| `basecamp_reports_overdue` | `basecamp reports overdue` |
| `basecamp_api` | `basecamp api` |
| `basecamp_url` | `basecamp url` |
| ... and 23 more | |

## License

MIT