| name | basecamp |
| description | Basecamp 2 integration via MCP. Covers MCP tool reference, URL parsing, authentication, Chrome fallback, attachments, and site-info documents. Use when reading or writing Basecamp data. |
| allowed-tools | ["Read","Bash","mcp__plugin_simpleapps_basecamp__*","mcp__claude-in-chrome__*"] |
Basecamp 2
IMPORTANT: MUST NOT create, edit, or delete anything in Basecamp without user permission.
Content format: All write tools MUST use plain text with line breaks, NOT HTML. Basecamp returns HTML in responses but prefers plain text for creation.
Setup
Credentials stored at ~/.simpleapps/basecamp.json. If missing, ask the user to run:
uv run basecamp-auth
This opens the browser for OAuth, user clicks "Allow", credentials are saved automatically.
MCP Tools
The basecamp MCP server is bundled with this plugin and starts automatically. API reference: https://github.com/basecamp/bcx-api
All tools are available as mcp__plugin_simpleapps_basecamp__*. The tool names and parameters are self-documenting via the MCP schema. Do not hardcode tool signatures. Key tool groups: projects, people, todos, comments, todo lists, messages, documents, calendar events, topics, attachments/uploads, activity, access management, stars, forwards.
Note: The BCX API does not have a search endpoint. To find content, use list_topics(project_id) to browse, or list_messages(project_id) for messages. For cross-project browsing, use list_topics() (no project_id) to get recent topics across all projects.
URL Parsing
A URL like https://basecamp.com/2805226/projects/18932786/todos/514631271 gives you project_id=18932786 and todo_id=514631271.
Base URL: https://basecamp.com/2805226
Downloading Attachments
Attachments can be on todos, comments, messages, or uploads. To retrieve them:
- Discover: Call
get_todo or get_message. Attachments appear with IDs in both the top-level section and within individual comments.
- Inspect (optional): Call
get_attachment(project_id, attachment_id) to see metadata, size, content type, and download URL
- Download: Call
download_attachment(project_id, attachment_id). Saves to ~/.simpleapps/downloads/{project_id}/.
- Read: Use the
Read tool on the local file path to view content (works for images, PDFs, Excel, text)
To browse all attachments in a project, use list_attachments(project_id).
Site Info Documents
Each Basecamp project SHOULD have a site-info text document in its Documents section. It contains site-specific details like siteId and domain name needed for GitHub issues and development work. Use list_documents + get_document to find it. If no site-info document exists, ask the user to create one.
Chrome Fallback
If the MCP server is unavailable (credentials expired, server not running), use Chrome:
- Use
tabs_context_mcp to get current tabs
- Create a new tab or use an existing Basecamp tab
- Navigate to the Basecamp page
- Use
get_page_text to extract content
Top nav: Projects | Calendar | Everything | Progress | Everyone | Me
| Page | Path |
|---|
| Dashboard | / |
| All projects | /projects |
| My assignments | click "Me" in top nav |
| Project overview | /projects/<project_id> |
| Todo lists | /projects/<project_id>/todolists |
| Documents | /projects/<project_id>/documents |
Me page (/people/<person_id>): open to-dos. When the list is long (roughly 45+ items), Basecamp truncates it and shows a "See all X open to-dos" link. If that link is present, YOU MUST click it to load the full list. The complete list is also at /people/<person_id>/outstanding_todos.
JSON API via Chrome: Navigate to /api/v1/projects/<project_id>/todos/<todo_id>.json then use get_page_text. WebFetch will NOT work; Chrome carries session cookies.
Tips
- Cache the user's
person_id on first visit for the session
- Start from
list_my_todos for "what do I need to work on?"
- Use
list_people to find person_id before calling assign_todo
- If you get a 401 or auth error, ask the user to re-run
basecamp-auth
- If an endpoint returns 404, the feature may not be available on this Basecamp plan
