@drkraft/basecamp-cli

A comprehensive command-line interface and MCP server for Basecamp 4. Manage projects, to-dos, messages, schedules, kanban boards, and more from your terminal or AI assistant.


Features

- Full CLI - 21 command groups covering the complete Basecamp 4 API
- MCP Server - 76 tools for AI assistant integration (Claude, etc.)
- Multiple Output Formats - Table or JSON output for all commands
- Pagination & Retry - Automatic handling of large datasets and rate limits
- OAuth 2.0 - Secure authentication via browser

Installation

``bash
npm install -g @drkraft/basecamp-cli
`

Or with bun:

`bash
bun add -g @drkraft/basecamp-cli
`

Requirements

- Node.js >= 18

Quick Start

$3

1. Go to Basecamp Integrations
2. Click "Register another application"
3. Fill in the details:
- Name: Your app name
- Company: Your company
- Website: Your website
- Redirect URI: http://localhost:9292/callback
4. Note your Client ID and Client Secret

$3

`bash
export BASECAMP_CLIENT_ID="your-client-id"
export BASECAMP_CLIENT_SECRET="your-client-secret"
`

Or configure via CLI:

`bash
basecamp auth configure --client-id "your-client-id"
`

$3

`bash
basecamp auth login
`

This opens your browser for OAuth authentication.

CLI Reference

$3

`bash
basecamp auth login # Login via OAuth
basecamp auth status # Check auth status
basecamp auth logout # Logout
`

$3

`bash
basecamp accounts # List available accounts
basecamp account set # Set current account
basecamp account current # Show current account
`

$3

`bash
basecamp projects list # List all projects
basecamp projects get # Get project details
basecamp projects create --name "Project" --description "Desc" # Create project
basecamp projects archive # Archive project
`

$3

`bash


To-do lists

basecamp todolists list --project
basecamp todolists create --project --name "Tasks"
basecamp todolists delete --project

To-dos

basecamp todos list --project --list
basecamp todos list --project --list --completed
basecamp todos get --project
basecamp todos create --project --list --content "Task"
basecamp todos create --project --list --content "Task" \
--due "2025-12-31" --assignees "123,456"
basecamp todos update --project --content "Updated"
basecamp todos complete --project
basecamp todos uncomplete --project
basecamp todos delete --project
basecamp todos move --project --list

To-do groups

basecamp todogroups list --project
basecamp todogroups create --project --name "Sprint 1"
`

$3

`bash
basecamp messages list --project
basecamp messages get --project
basecamp messages create --project --subject "Subject" --content "

HTML

"
`

$3

`bash
basecamp campfires list --project
basecamp campfires lines --project --campfire
basecamp campfires send --project --campfire --message "Hello!"
`

$3

`bash
basecamp comments list --project --recording
basecamp comments get --project
basecamp comments create --project --recording --content "

Comment

"
basecamp comments update --project --content "

Updated

"
basecamp comments delete --project
`

$3

`bash


Vaults (folders)

basecamp vaults list --project
basecamp vaults get --project
basecamp vaults create --project --vault --title "Folder Name"

Documents

basecamp documents list --project --vault
basecamp documents get --project
basecamp documents create --project --vault --title "Doc" --content "

...

"
basecamp documents update --project --title "New Title"

Uploads

basecamp uploads list --project --vault
basecamp uploads get --project
`

$3

`bash
basecamp schedules get --project
basecamp schedules entries --project
basecamp schedules entries --project --status upcoming
basecamp schedules create-entry --project --summary "Meeting" \
--starts-at "2025-02-15T10:00:00" --ends-at "2025-02-15T11:00:00"
basecamp schedules update-entry --project --summary "Updated"
basecamp schedules delete-entry --project
`

$3

`bash
basecamp cardtables get --project
basecamp cardtables columns --project
basecamp cardtables create-column --project --title "In Progress"
basecamp cardtables cards --project --column
basecamp cardtables create-card --project --column --title "Card"
basecamp cardtables move-card --project --column
`

$3

`bash
basecamp webhooks list --project
basecamp webhooks get --project
basecamp webhooks create --project --payload-url "https://..."
basecamp webhooks update --project --active false
basecamp webhooks delete --project
`

$3

`bash


Recordings (cross-project content)

basecamp recordings list --type Todo
basecamp recordings list --type Message --status archived
basecamp recordings archive --project
basecamp recordings restore --project
basecamp recordings trash --project

Events (activity feed)

basecamp events list --project --recording
`

$3

`bash
basecamp subscriptions list --project --recording
basecamp subscriptions subscribe --project --recording
basecamp subscriptions unsubscribe --project --recording
`

$3

`bash
basecamp search "keyword"
basecamp search "keyword" --type Todo
basecamp search "keyword" --project
`

$3

`bash
basecamp people list
basecamp people list --project
basecamp people get
basecamp people me
`

Output Formats

All commands support --format flag:

`bash
basecamp projects list --format table # Default, human-readable
basecamp projects list --format json # JSON for scripting
`

Global Options

`bash
basecamp --verbose projects list # Enable debug output
basecamp -v people me # Short form
`

MCP Server

The CLI includes an MCP (Model Context Protocol) server for AI assistant integration.

$3

`bash
basecamp-mcp


Or


bun run mcp
`

$3

| Category | Tools |
|----------|-------|
| Projects | basecamp_list_projects, basecamp_get_project, basecamp_create_project, basecamp_archive_project |
| Todo Lists | basecamp_list_todolists, basecamp_get_todolist, basecamp_create_todolist, basecamp_delete_todolist |
| Todo Groups | basecamp_list_todolist_groups, basecamp_create_todolist_group |
| Todos | basecamp_list_todos, basecamp_get_todo, basecamp_create_todo, basecamp_update_todo, basecamp_complete_todo, basecamp_uncomplete_todo, basecamp_delete_todo, basecamp_move_todo |
| Messages | basecamp_list_messages, basecamp_get_message, basecamp_create_message |
| People | basecamp_list_people, basecamp_get_person, basecamp_get_me |
| Comments | basecamp_list_comments, basecamp_get_comment, basecamp_create_comment, basecamp_update_comment, basecamp_delete_comment |
| Vaults | basecamp_list_vaults, basecamp_get_vault, basecamp_create_vault, basecamp_update_vault |
| Documents | basecamp_list_documents, basecamp_get_document, basecamp_create_document, basecamp_update_document |
| Uploads | basecamp_list_uploads, basecamp_get_upload, basecamp_create_upload, basecamp_update_upload |
| Schedules | basecamp_get_schedule, basecamp_list_schedule_entries, basecamp_get_schedule_entry, basecamp_create_schedule_entry, basecamp_update_schedule_entry, basecamp_delete_schedule_entry |
| Card Tables | basecamp_get_card_table, basecamp_get_column, basecamp_create_column, basecamp_update_column, basecamp_delete_column, basecamp_list_cards, basecamp_get_card, basecamp_create_card, basecamp_update_card, basecamp_move_card, basecamp_delete_card |
| Search | basecamp_search |
| Recordings | basecamp_list_recordings, basecamp_archive_recording, basecamp_restore_recording, basecamp_trash_recording |
| Subscriptions | basecamp_list_subscriptions, basecamp_subscribe, basecamp_unsubscribe |
| Webhooks | basecamp_list_webhooks, basecamp_get_webhook, basecamp_create_webhook, basecamp_update_webhook, basecamp_delete_webhook, basecamp_test_webhook |
| Events | basecamp_list_events |
| Campfires | basecamp_list_campfires, basecamp_get_campfire_lines, basecamp_send_campfire_line |

$3

Add to your MCP configuration:

`json
{
"mcpServers": {
"basecamp": {
"command": "basecamp-mcp",
"env": {
"BASECAMP_CLIENT_ID": "",
"BASECAMP_CLIENT_SECRET": ""
}
}
}
}
`

Or with explicit path:

`json
{
"mcpServers": {
"basecamp": {
"command": "node",
"args": ["/path/to/node_modules/@drkraft/basecamp-cli/dist/mcp.js"]
}
}
}
`

Environment Variables

| Variable | Description |
|----------|-------------|
| BASECAMP_CLIENT_ID | OAuth Client ID (required) |
| BASECAMP_CLIENT_SECRET | OAuth Client Secret (required) |
| BASECAMP_REDIRECT_URI | OAuth Redirect URI (default: http://localhost:9292/callback) |

API Coverage

This CLI covers the complete Basecamp 4 API Tier 1 domains:

| Domain | Status |
|--------|--------|
| Projects | Complete |
| Todolists | Complete |
| Todos | Complete |
| Todolist Groups | Complete |
| Messages | Complete |
| Campfires | Complete |
| Comments | Complete |
| Vaults | Complete |
| Documents | Complete |
| Uploads | Complete |
| Schedules | Complete |
| Card Tables | Complete |
| Webhooks | Complete |
| Recordings | Complete |
| Events | Complete |
| Search | Complete |
| Subscriptions | Complete |
| People | Complete |

Development

`bash


Clone the repo

git clone https://github.com/drkraft/basecamp-cli
cd basecamp-cli

Install dependencies

bun install

Build

bun run build

Run tests

bun test

Run validation against real Basecamp

bun run scripts/validate.ts
``

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE for details.

Credits

Originally forked from @emredoganer/basecamp-cli.