README.md•5.08 kB
# Basecamp MCP Server
Model Context Protocol (MCP) server for Basecamp integration. Enables LLMs to interact with Basecamp projects, messages, todos, comments, people, and kanban boards.
## Getting Started
The Basecamp MCP server requires Node.js 18+ and works with various MCP clients including Claude Code CLI, Claude Desktop, Cursor, VS Code, and others.
### Standard Configuration
The baseline setup applies across most tools:
```json
{
"mcpServers": {
"basecamp": {
"command": "npx",
"args": ["-y", "basecamp-mcp@latest"],
"env": {
"BASECAMP_CLIENT_ID": "your_client_id",
"BASECAMP_CLIENT_SECRET": "your_client_secret",
"BASECAMP_REFRESH_TOKEN": "your_refresh_token",
"BASECAMP_USER_AGENT": "YourApp (your@email.com)",
"BASECAMP_ACCOUNT_ID": "account_id"
}
}
}
}
```
### Installation by Client
**Claude Code CLI:**
```bash
claude mcp add basecamp npx basecamp-mcp@latest \
-e BASECAMP_CLIENT_ID=your_client_id \
-e BASECAMP_CLIENT_SECRET=your_client_secret \
-e BASECAMP_REFRESH_TOKEN=your_refresh_token \
-e BASECAMP_USER_AGENT="YourApp (your@email.com)" \
-e BASECAMP_ACCOUNT_ID=account_id
```
**Claude Desktop:** Follow the MCP install guide using the standard config above.
**Cursor:** One-click installation available, or manually add configuration through Settings → Tools & Integrations → New MCP Server.
**VS Code:** One-click installation provided, or use the CLI:
```bash
code --add-mcp '{"name":"basecamp","command":"npx","args":["-y", "basecamp-mcp@latest"]}'
```
**Gemini CLI & Windsurf:** Refer to their respective documentation; use the standard config template.
## Configuration
The server requires the following environment variables:
* **`BASECAMP_CLIENT_ID`** — Your Basecamp OAuth client ID
* **`BASECAMP_CLIENT_SECRET`** — Your Basecamp OAuth client secret
* **`BASECAMP_REFRESH_TOKEN`** — Your Basecamp refresh token for authentication
* **`BASECAMP_USER_AGENT`** — Your application identifier (format: YourApp (our@email.com))
* **`BASECAMP_ACCOUNT_ID`** — Your Basecamp account ID
### Complete Configuration Example
```json
{
"mcpServers": {
"basecamp": {
"command": "npx",
"args": ["-y", "basecamp-mcp@latest"],
"env": {
"BASECAMP_CLIENT_ID": "your_client_id",
"BASECAMP_CLIENT_SECRET": "your_client_secret",
"BASECAMP_REFRESH_TOKEN": "your_refresh_token",
"BASECAMP_USER_AGENT": "YourApp (your@email.com)",
"BASECAMP_ACCOUNT_ID": "account_id"
}
}
}
}
```
## Usage
### Running the Server
```bash
npm start
```
Or for development with auto-reload:
```bash
npm run dev
```
### Available Tools
#### Projects
- `basecamp_list_projects` - List all accessible projects with optional filtering
- `basecamp_get_project` - Get detailed project information including dock configuration
#### Messages
- `basecamp_list_messages` - List messages in a message board with optional filtering
- `basecamp_list_message_types` - List available message types/categories for a project
- `basecamp_get_message` - Get single message details
- `basecamp_create_message` - Create new message with optional category and draft status
- `basecamp_update_message` - Update message with advanced content editing (supports full replacement, append, prepend, search/replace)
#### TODOs
- `basecamp_get_todoset` - Get todo set container with all todo lists
- `basecamp_list_todos` - List todos in a list with status filtering (active/archived)
- `basecamp_create_todo` - Create new todo with optional description
- `basecamp_complete_todo` - Mark todo as complete
- `basecamp_uncomplete_todo` - Mark todo as incomplete
#### Comments
- `basecamp_list_comments` - List comments on any resource (works universally on all recording types)
- `basecamp_create_comment` - Add comment to any resource
- `basecamp_update_comment` - Update comment with advanced content editing (supports full replacement, append, prepend, search/replace)
#### People
- `basecamp_get_me` - Get personal information for the authenticated user
- `basecamp_list_people` - List all people with optional filtering by name, email, or title
- `basecamp_get_person` - Get person details
#### Kanban
- `basecamp_list_kanban_columns` - List all columns in a kanban board
- `basecamp_list_kanban_cards` - List cards in a column with steps and assignees
- `basecamp_get_kanban_card` - Get complete details of a specific card
- `basecamp_create_kanban_card` - Create new card with title and optional content
- `basecamp_update_kanban_card` - Update card with advanced content editing (supports full replacement, append, prepend, search/replace, plus title, due date, assignees, notifications)
- `basecamp_move_kanban_card` - Move a card to a different column and/or position
- `basecamp_create_kanban_step` - Add checklist step to a card
## Development
```bash
# Install dependencies
npm install
# Run type checking
npx tsc --noEmit
# Build
npm run build
# Clean build artifacts
npm run clean
```
## License
MIT