Skip to content
Back to search

Basecamp-MCP-Server

MCP server for Basecamp 3 with OAuth, FastMCP, and 75 tools for projects, todos, messages, card tables, docs, uploads, and search.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/georgeantonopoulos/Basecamp-MCP-Server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/georgeantonopoulos/Basecamp-MCP-Server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/georgeantonopoulos--basecamp-mcp-server/badge.svg)](/listings/georgeantonopoulos--basecamp-mcp-server)

HTML

<a href="/listings/georgeantonopoulos--basecamp-mcp-server"><img src="/api/listings/georgeantonopoulos--basecamp-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone the repository and install dependencies:

git clone https://github.com/georgeantonopoulos/Basecamp-MCP-Server.git
cd Basecamp-MCP-Server

uv venv --python 3.12 venv
source venv/bin/activate
uv pip install -r requirements.txt

Or, if `python` already points to Python 3.10 or newer:

python setup.py

Create a `.env` file from the example and fill in your Basecamp OAuth details:

cp .env.example .env

Required values:

BASECAMP_CLIENT_ID=your-client-id
BASECAMP_CLIENT_SECRET=your-client-secret
BASECAMP_ACCOUNT_ID=your-account-id
USER_AGENT="Your App Name (your@email.com)"

Authenticate with Basecamp:

python oauth_app.py

Open <http://localhost:8000> and complete the OAuth flow. The token is stored locally in `oauth_tokens.json` by default.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 547 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Basecamp MCP Server
  2. [![PyPI](https://img.shields.io/pypi/v/basecamp-mcp-server.svg)](https://pypi.org/project/basecamp-mcp-server/)
  3. [![Tests](https://github.com/georgeantonopoulos/Basecamp-MCP-Server/actions/workflows/tests.yml/badge.svg)](https://github.com/georgeantonopoulos/Basecamp-MCP-Server/actions/workflows/tests.yml)
  4. [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  6. Connect Claude, Cursor, Codex and other AI assistants to your **Basecamp 3 or 4** account. Ask in plain language to find, read, create and update projects, to-dos, messages, card tables, schedules, documents and more: 210 Basecamp operations in all.
  7. > "What's overdue across all my projects?" · "Summarise this week's messages in the Website project." · "Move this card to Done and comment that it shipped."
  8. ## Contents
  9. - [Quick start](#quick-start)
  10. - [Add it to your AI app](#add-it-to-your-ai-app)
  11. - [What it can do](#what-it-can-do)
  12. - [All 210 tools](#all-210-tools)
  13. - [Settings and sign-in](#settings-and-sign-in)
  14. - [Troubleshooting](#troubleshooting)
  15. - [Run from a git checkout](#run-from-a-git-checkout)
  16. - [Security](#security)
  17. ## Quick start
  18. You need [uv](https://docs.astral.sh/uv/getting-started/installation/) (it installs Python for you) and a Basecamp 3 or 4 account. Setup takes about five minutes.
  19. **1. Install uv**, if you don't have it:
  20. ```bash
  21. # macOS and Linux
  22. curl -LsSf https://astral.sh/uv/install.sh | sh
  23. ```
  24. ```powershell
  25. # Windows
  26. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  27. ```
  28. **2. Sign in to Basecamp:**
  29. ```bash
  30. uvx basecamp-mcp-server login
  31. ```
  32. The first time, it walks you through registering a free Basecamp app at [launchpad.37signals.com/integrations](https://launchpad.37signals.com/integrations) (set its **Redirect URI** to `http://localhost:8000/auth/callback`), then asks for the Client ID and Client Secret it shows you. Your browser then opens for Basecamp sign-in, and the token is saved for you. Tokens refresh automatically after that.
  33. **3. Add the server to your AI app**, using the snippet from the next section, and restart the app.
  34. Check everything is working at any time:
  35. ```bash
  36. uvx basecamp-mcp-server status
  37. ```
  38. ## Add it to your AI app
  39. `uvx basecamp-mcp-server config <app>` prints the exact snippet for your machine. The app can be `claude-desktop`, `cursor`, `claude-code`, `codex` or `generic`.
  40. <details open>
  41. <summary><b>Claude Desktop</b></summary>
  42. Open **Settings → Developer → Edit Config** and add:
  43. ```json
  44. {
  45. "mcpServers": {
  46. "basecamp": {
  47. "command": "uvx",
  48. "args": ["basecamp-mcp-server"]
  49. }
  50. }
  51. }
  52. ```
  53. Quit Claude Desktop completely and reopen it. If it says it can't find `uvx`, use the full path that `uvx basecamp-mcp-server config claude-desktop` prints.
  54. </details>
  55. <details>
  56. <summary><b>Claude Code</b></summary>
  57. ```bash
  58. claude mcp add basecamp -- uvx basecamp-mcp-server
  59. ```
  60. </details>
  61. <details>
  62. <summary><b>Cursor</b></summary>
  63. Add the same JSON as Claude Desktop to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project), then restart Cursor and check **Settings → MCP**.
  64. </details>
  65. <details>
  66. <summary><b>Codex</b></summary>
  67. Add to `~/.codex/config.toml`:
  68. ```toml
  69. [mcp_servers.basecamp]
  70. command = "uvx"
  71. args = ["basecamp-mcp-server"]
  72. ```
  73. </details>
  74. <details>
  75. <summary><b>Any other MCP client</b></summary>
  76. Run `uvx basecamp-mcp-server` as a local (stdio) MCP server. The JSON above works for most clients.
  77. </details>
  78. ### Four tools or all 210?
  79. By default the server shows your AI app **four small tools** that find and run the right Basecamp operation on demand. That keeps the app's context small, and it can still reach all 210 operations. Reading and changing data are separate tools, so apps that ask before making changes still do.
  80. To list all 210 tools up front instead, add `--full`: `"args": ["basecamp-mcp-server", "--full"]`.
  81. ### Run it as a web address (HTTP)
  82. Apps that connect to a URL instead of starting a program, such as claude.ai custom connectors, can use HTTP mode. Each person who connects signs in with their own Basecamp login, and everything they do runs as them. No token is shared.
  83. 1. In your Basecamp app at [launchpad.37signals.com/integrations](https://launchpad.37signals.com/integrations), set the Redirect URI to `https://<your address>/auth/callback`.
  84. 2. Put the app's Client ID and Secret in the settings `.env` (or run `login` once), then start the server behind HTTPS:
  85. ```bash
  86. uvx basecamp-mcp-server serve --host 0.0.0.0 --port 8765 --public-url https://basecamp-mcp.example.com
  87. ```
  88. 3. In claude.ai, add a custom connector with the URL `https://basecamp-mcp.example.com/mcp`. Connecting it opens Basecamp's sign-in; people with several Basecamp accounts pick one.
  89. The server speaks plain HTTP, so put a reverse proxy or tunnel in front for HTTPS. `--public-url` is the address people reach it at. To try it on your own machine, `serve --port 8000` uses `http://localhost:8000` and the default `http://localhost:8000/auth/callback` Redirect URI. Sign-ins are kept in `http_oauth.json` in the settings folder, with this server's own tokens stored only as hashes.
  90. **Just for yourself?** `serve --auth key` skips per-person sign-in and uses the token saved by `login`. Every request must then carry an access key, which the first run creates, saves as `BASECAMP_MCP_HTTP_TOKEN` and prints with a ready-made command:
  91. ```bash
  92. claude mcp add --transport http basecamp http://127.0.0.1:8765/mcp --header "Authorization: Bearer <key>"
  93. ```
  94. `--full` works in both modes: `serve --full`.
  95. ## What it can do
  96. - **Projects and people:** list, create and update projects and templates; see who's on a project and grant or revoke access.
  97. - **To-dos:** read, create, assign, complete, move and archive to-dos and to-do lists; see what's assigned to anyone and what's overdue.
  98. - **Messages and comments:** read and post messages (or save drafts), pin them, manage categories, and comment on anything.
  99. - **Chat and check-ins:** read and post in Campfire chats; create, pause and read automatic check-in questions and answers.
  100. - **Schedules:** read, create and update events, including recurring ones.
  101. - **Card tables:** work with columns, cards and card steps; move cards between columns.
  102. - **Files and documents:** list, read and create documents; download uploads and inline attachments straight into the conversation.
  103. - **Search and activity:** search the whole account; browse activity timelines and account-wide feeds of messages, files, to-dos and cards.
  104. - **Time and progress:** timesheets, progress gauges and Hill Charts.
  105. - **Personal and admin:** notifications, bookmarks, your private note, subscriptions, webhooks and project tools.
  106. Big lists (projects, to-dos, comments, messages, cards, assignments) come back as compact summaries so they fit in the AI's context. Those tools take `detail: "full"` when you need every field, or set `BASECAMP_MCP_FULL_RESPONSES=1` to make that the default.
  107. ## All 210 tools
  108. Grouped the same way the server groups them for discovery. Click a group to expand it.
  109. <details>
  110. <summary><b>Projects and people</b> (18 tools)</summary>
  111. - `create_project` — Create a Basecamp project
  112. - `create_project_from_template` — Start constructing a project from a Basecamp template
  113. - `create_template` — Create a Basecamp project template
  114. - `get_assignable_people` — Get all people who can have to-dos assigned to them
  115. - `get_people` — Get people available in the authenticated Basecamp account
  116. - `get_person` — Get one Basecamp person's profile
  117. - `get_pingable_people` — Get Basecamp people who can be pinged
  118. - `get_project` — Get one project's details, including its dock IDs
  119. - `get_project_construction` — Get the status of a project being constructed from a template
  120. - `get_project_people` — Get active people on a Basecamp project
  121. - `get_projects` — List Basecamp projects. Returns a compact summary by default
  122. - `get_template` — Get a Basecamp project template
  123. - `get_templates` — List visible Basecamp project templates
  124. - `trash_project` — Move a Basecamp project to the trash
  125. - `trash_template` — Move a Basecamp project template to the trash
  126. - `update_project` — Update a project's name, description, access policy, or date range
  127. - `update_project_people` — Grant, revoke, or invite people on a Basecamp project
  128. - `update_template` — Update a Basecamp project template
  129. </details>
  130. <details>
  131. <summary><b>Todos and assignments</b> (25 tools)</summary>
  132. - `archive_todo` — Archive a todo item
  133. - `complete_todo` — Mark a todo item as complete
  134. - `create_todo` — Create a new todo item in a todo list
  135. - `create_todolist` — Create a new todo list in a project
  136. - `create_todolist_group` — Create a new group inside a todo list
  137. - `delete_todo` — Move a todo item to the trash
  138. - `deprioritize_assignment` — Remove an assignment from the authenticated user's Up Next list
  139. - `get_completed_assignments` — Get the authenticated user's completed assignments
  140. - `get_due_assignments` — Get the authenticated user's assignments by due-date scope
  141. - `get_my_assignments` — Get the authenticated user's active assignments grouped by priority
  142. - `get_overdue_todos` — Get overdue to-dos for the WHOLE ACCOUNT, grouped by how late they are
  143. - `get_person_assignments` — Get all active, pending to-dos assigned to a specific person
  144. - `get_todo` — Get a single todo item by its ID
  145. - `get_todolist` — Get a specific todo list by ID
  146. - `get_todolist_groups` — Get all groups in a todo list
  147. - `get_todolists` — Get todo lists for a project
  148. - `get_todos` — Get todos from a todo list
  149. - `prioritize_assignment` — Add an assignment to the authenticated user's Up Next list
  150. - `reorder_priority` — Move an assignment to a position in the authenticated user's Up Next list
  151. - `reposition_todo` — Reposition a todo within its list, or move it to another list or group
  152. - `reposition_todolist_group` — Reposition a todo list group to a new location within its list
  153. - `trash_todolist` — Move a todo list to the trash
  154. - `uncomplete_todo` — Mark a todo item as incomplete
  155. - `update_todo` — Update an existing todo item
  156. - `update_todolist` — Update an existing todo list
  157. </details>
  158. <details>
  159. <summary><b>Messages and comments</b> (24 tools)</summary>
  160. - `create_comment` — Create a comment on a Basecamp item
  161. - `create_draft_message` — Create a draft message on a project's message board without publishing it
  162. - `create_message` — Create a new message on a project's message board
  163. - `create_message_category` — Create a message type/category
  164. - `delete_comment` — Delete a comment by moving it to the project's trash (Basecamp has no hard delete)
  165. - `delete_message_category` — Delete a message type/category
  166. - `get_comment` — Get a specific comment by ID
  167. - `get_comments` — Get comments for a Basecamp item
  168. - `get_forward` — Get a specific forwarded email by ID
  169. - `get_forwards` — Get all forwarded emails from a project's inbox
  170. - `get_inbox` — Get the inbox for a project (for email forwards)
  171. - `get_inbox_replies` — Get all replies to a forwarded email
  172. - `get_inbox_reply` — Get a specific reply to a forwarded email
  173. - `get_message` — Get a specific message by ID
  174. - `get_message_board` — Get the message board for a project
  175. - `get_message_categories` — Get message categories (types) for a project
  176. - `get_message_category` — Get one message type/category
  177. - `get_messages` — Get all messages from a project's message board
  178. - `pin_message` — Pin a message to the top of its message board
  179. - `trash_forward` — Move a forwarded email to trash
  180. - `unpin_message` — Remove a message from the top of its message board
  181. - `update_comment` — Update a comment's content
  182. - `update_message` — Update one or more fields on a message
  183. - `update_message_category` — Update a message type/category
  184. </details>
  185. <details>
  186. <summary><b>Campfires and check-ins</b> (17 tools)</summary>
  187. - `create_campfire_line` — Create a plain-text line in a Basecamp campfire
  188. - `create_question` — Create a question in a Basecamp automatic check-ins questionnaire
  189. - `delete_campfire_line` — Permanently delete a line from a Basecamp campfire
  190. - `get_campfire_line` — Get one line from a Basecamp campfire
  191. - `get_campfire_lines` — Get recent messages from a Basecamp campfire (chat room)
  192. - `get_campfires` — List campfire/chat rooms enabled in a project
  193. - `get_daily_check_ins` — Get project's daily checking questionnaire
  194. - `get_question` — Get one automatic check-in question
  195. - `get_question_answer` — Get one automatic check-in answer
  196. - `get_question_answerers` — List people who have answered a Basecamp automatic check-in question
  197. - `get_question_answers` — Get answers on daily check-in question
  198. - `get_question_reminders` — Get pending automatic check-in reminders for the authenticated user
  199. - `get_questionnaire` — Get the automatic check-ins questionnaire for a project
  200. - `get_questions` — Get questions from an automatic check-ins questionnaire
  201. - `pause_question` — Pause a Basecamp automatic check-in question
  202. - `resume_question` — Resume a paused Basecamp automatic check-in question
  203. - `update_question` — Update selected fields on a Basecamp automatic check-in question
  204. </details>
  205. <details>
  206. <summary><b>Schedules and calendars</b> (13 tools)</summary>
  207. - `create_lineup_marker` — Create an account-wide Basecamp Lineup marker
  208. - `create_schedule_entry` — Create a schedule entry in a Basecamp project's schedule
  209. - `delete_lineup_marker` — Delete an account-wide Basecamp Lineup marker
  210. - `get_calendar` — Get a Basecamp calendar by ID
  211. - `get_lineup_markers` — List account-wide Basecamp Lineup markers
  212. - `get_schedule` — Get the schedule for a Basecamp project
  213. - `get_schedule_entries` — Get schedule entries for a Basecamp project
  214. - `get_schedule_entry` — Get one schedule entry from a Basecamp project
  215. - `get_schedule_entry_occurrence` — Get one occurrence of a recurring schedule entry
  216. - `get_upcoming_schedule` — Get upcoming events and due work across all accessible projects
  217. - `update_calendar` — Update a Basecamp calendar's display color
  218. - `update_lineup_marker` — Update an account-wide Basecamp Lineup marker
  219. - `update_schedule_entry` — Update one or more fields on a Basecamp schedule entry
  220. </details>
  221. <details>
  222. <summary><b>Card tables</b> (29 tools)</summary>
  223. - `complete_card` — Mark a card as complete
  224. - `complete_card_step` — Mark a card step as complete
  225. - `create_card` — Create a new card in a column
  226. - `create_card_step` — Create a new step (sub-task) for a card
  227. - `create_card_table_wormhole` — Create a cross-project card-table wormhole
  228. - `create_column` — Create a new column in a card table
  229. - `delete_card_step` — Delete a card step
  230. - `delete_card_table_wormhole` — Delete a card-table wormhole
  231. - `get_card` — Get details for a specific card
  232. - `get_card_step` — Get details for a specific card step
  233. - `get_card_steps` — Get all steps (sub-tasks) for a card
  234. - `get_card_table` — Get the card table details for a project, including its columns
  235. - `get_card_tables` — Get all card tables for a project
  236. - `get_cards` — Get all cards in a column
  237. - `get_column` — Get details for a specific column
  238. - `get_columns` — Get all columns in a card table
  239. - `move_card` — Move a card to a column or linked cross-project wormhole
  240. - `move_column` — Move a column to a new position
  241. - `put_column_on_hold` — Put a column on hold (freeze work)
  242. - `remove_column_hold` — Remove hold from a column (unfreeze work)
  243. - `uncomplete_card` — Mark a card as incomplete
  244. - `uncomplete_card_step` — Mark a card step as incomplete
  245. - `unwatch_column` — Unsubscribe from notifications for a column
  246. - `update_card` — Update a card
  247. - `update_card_step` — Update a card step
  248. - `update_card_table_wormhole` — Change a card-table wormhole's destination column
  249. - `update_column` — Update a column title
  250. - `update_column_color` — Update a column color
  251. - `watch_column` — Subscribe to notifications for changes in a column
  252. </details>
  253. <details>
  254. <summary><b>Files and documents</b> (20 tools)</summary>
  255. - `archive_recording` — Archive any Basecamp recording
  256. - `create_attachment` — Upload a file as an attachment
  257. - `create_document` — Create a document in a vault
  258. - `create_draft_document` — Create a draft document in a vault without publishing it
  259. - `create_upload_version` — Replace an upload's file while preserving its recording URL
  260. - `download_attachment` — Download an inline comment/message attachment as MCP content
  261. - `download_upload` — Download the binary content of an upload (PDF, image, document, ...)
  262. - `get_document` — Get a single document
  263. - `get_documents` — List documents in a vault
  264. - `get_recordings` — List every recording of one supported type in a project or account
  265. - `get_upload` — Get details for a specific upload
  266. - `get_upload_versions` — Get raw version events for an upload, optionally filtered by action
  267. - `get_uploads` — List uploads in a project or vault
  268. - `get_vaults` — List child vaults in a vault
  269. - `restore_recording` — Restore an archived Basecamp recording to active status
  270. - `trash_document` — Move a document to trash
  271. - `trash_recording` — Move any Basecamp recording to the trash
  272. - `update_document` — Update a document
  273. - `update_recording_visibility` — Toggle client visibility for a Basecamp recording
  274. - `update_upload` — Update an upload's metadata without replacing its file
  275. </details>
  276. <details>
  277. <summary><b>Search, activity, and reports</b> (15 tools)</summary>
  278. - `get_events` — Get events for a recording
  279. - `get_everything_cards` — Get filtered cards grouped by project across the whole account
  280. - `get_everything_checkins` — Get automatic check-in answers across every accessible project
  281. - `get_everything_comments` — Get recent comments across every accessible Basecamp project
  282. - `get_everything_files` — Get files across every accessible project, optionally filtered by kind or creator
  283. - `get_everything_forwards` — Get inbox forwards across every accessible Basecamp project
  284. - `get_everything_messages` — Get recent messages across every accessible Basecamp project
  285. - `get_everything_todos` — Get filtered to-dos grouped by project across the whole account
  286. - `get_person_timeline` — Get timeline activity created by one Basecamp person
  287. - `get_project_timeline` — Get recent activity within one Basecamp project
  288. - `get_search_metadata` — Get the valid filters and content types for native Basecamp search
  289. - `get_timeline` — Get recent activity across every accessible Basecamp project
  290. - `global_search` — Search projects, todos and campfire messages across all projects
  291. - `search_basecamp` — Search across Basecamp projects, todos, and messages
  292. - `search_recordings` — Search Basecamp content, returning one page or at most ``limit`` results
  293. </details>
  294. <details>
  295. <summary><b>Timesheets and progress</b> (17 tools)</summary>
  296. - `create_gauge_needle` — Record a new progress update for a Basecamp project gauge
  297. - `create_timesheet_entry` — Log time against a Basecamp timesheetable recording
  298. - `delete_gauge_needle` — Permanently delete a Basecamp gauge needle
  299. - `delete_timesheet_entry` — Permanently delete a Basecamp timesheet entry
  300. - `get_gauge_needle` — Get one Basecamp gauge needle
  301. - `get_gauge_needles` — Get a project's gauge history, newest first
  302. - `get_gauges` — List project gauges across the authenticated Basecamp account
  303. - `get_hill_chart` — Get the Basecamp Hill Chart for a to-do set
  304. - `get_project_hill_chart` — Resolve and get a project's Basecamp Hill Chart
  305. - `get_project_timesheet` — Get paginated timesheet entries for a Basecamp project
  306. - `get_recording_timesheet` — Get paginated timesheet entries for a Basecamp recording
  307. - `get_timesheet_entry` — Get one Basecamp timesheet entry
  308. - `get_timesheet_report` — Get the account-wide, non-paginated Basecamp timesheet report
  309. - `toggle_gauge` — Enable or disable a Basecamp project's gauge
  310. - `update_gauge_needle` — Update the description of a Basecamp gauge needle
  311. - `update_hill_chart_settings` — Track or untrack to-do lists on a Basecamp Hill Chart
  312. - `update_timesheet_entry` — Update selected fields on a Basecamp timesheet entry
  313. </details>
  314. <details>
  315. <summary><b>Notifications and personal tools</b> (16 tools)</summary>
  316. - `create_bookmark` — Bookmark a Basecamp recording for the authenticated user
  317. - `delete_bookmark` — Remove a recording from the authenticated user's bookmarks
  318. - `get_bookmark_status` — Get the authenticated user's bookmark status for a recording
  319. - `get_bubble_ups` — Get the authenticated user's current and scheduled bubble-ups
  320. - `get_my_bookmarks` — Get recordings bookmarked by the authenticated user
  321. - `get_my_drafts` — Get unpublished drafts owned by the authenticated user
  322. - `get_my_note` — Get the authenticated user's personal Basecamp note
  323. - `get_my_profile` — Get the authenticated person's Basecamp profile
  324. - `get_notifications` — Get the authenticated user's grouped Basecamp notification inbox
  325. - `get_subscription` — Get subscription state and subscribers for a Basecamp recording
  326. - `mark_notifications_read` — Mark notification readable SGIDs as read
  327. - `subscribe_to_recording` — Subscribe the authenticated user to a Basecamp recording
  328. - `unsubscribe_from_recording` — Unsubscribe the authenticated user from a Basecamp recording
  329. - `update_my_note` — Replace the authenticated user's personal Basecamp note
  330. - `update_question_notification_settings` — Update the authenticated user's automatic check-in notification settings
  331. - `update_subscription` — Add or remove people from a recording's subscriber list
  332. </details>
  333. <details>
  334. <summary><b>Administration and integrations</b> (16 tools)</summary>
  335. - `create_dock_tool` — Add a tool to a Basecamp project's dock
  336. - `create_webhook` — Create a webhook
  337. - `delete_webhook` — Delete a webhook
  338. - `disable_dock_tool` — Hide a recording from a Basecamp project's dock without deleting it
  339. - `enable_dock_tool` — Enable a recording in a Basecamp project's dock
  340. - `get_account` — Get the Basecamp account associated with the current access token
  341. - `get_dock_tool` — Get one Basecamp project dock tool
  342. - `get_webhook` — Get one project webhook and its recent deliveries
  343. - `get_webhooks` — List webhooks for a project
  344. - `remove_account_logo` — Remove the account logo (administrator/owner only)
  345. - `reposition_dock_tool` — Move a Basecamp project dock tool to a one-based position
  346. - `trash_dock_tool` — Permanently delete a Basecamp dock tool and its content
  347. - `update_account_logo` — Upload or replace the account logo (administrator/owner only)
  348. - `update_account_name` — Rename the current Basecamp account (owner only)
  349. - `update_dock_tool` — Rename a Basecamp project dock tool
  350. - `update_webhook` — Update a project webhook destination, event types, or active state
  351. </details>
  352. > **Reading files in chat.** `download_upload` and `download_attachment` return files as MCP content. Claude Code passes PDFs, images and other files to the model. Claude Desktop and claude.ai currently pass images only; other file types are rejected by the app, not by this server.
  353. ## Settings and sign-in
  354. The installed server keeps its settings in one folder:
  355. | System | Folder |
  356. | --- | --- |
  357. | macOS and Linux | `~/.config/basecamp-mcp-server/` (or `$XDG_CONFIG_HOME/basecamp-mcp-server/`) |
  358. | Windows | `%APPDATA%\basecamp-mcp-server\` |
  359. It holds `.env` (your Basecamp app's Client ID and Secret), `oauth_tokens.json` (your sign-in) and log files. The `.env` and token files are readable only by you. To use a different folder, set `BASECAMP_MCP_HOME`.
  360. **Several Basecamp accounts?** `login` asks which one to use, or you can pass `--account-id 1234567`. The ID is the number in your Basecamp URL: `https://3.basecamp.com/1234567/projects`.
  361. **Signing in on a machine without a browser?** Run `uvx basecamp-mcp-server login --no-browser`, open the printed link on any browser that can reach `localhost` on that machine, and approve.
  362. **Other settings** go in the environment or as lines in the settings `.env` file. `BASECAMP_MCP_HOME` is the exception: it says where that file is, so set it in the environment, or in your AI app's `env` block (`config` adds it for you).
  363. | Variable | What it does |
  364. | --- | --- |
  365. | `BASECAMP_MCP_HOME` | Settings folder (see above). Environment only. |
  366. | `BASECAMP_MCP_TOKEN_FILE` | Token file location, for example on a mounted volume. |
  367. | `BASECAMP_REDIRECT_URI` | Must match your Basecamp app. Default `http://localhost:8000/auth/callback`. |
  368. | `BASECAMP_ACCOUNT_ID` | Fallback account if the token doesn't record one. |
  369. | `USER_AGENT` | Name sent to Basecamp's API. Basecamp asks for contact details; the default points to this project. |
  370. | `BASECAMP_MCP_HTTP_AUTH` | `oauth` (default) or `key` for `serve`. |
  371. | `BASECAMP_MCP_PUBLIC_URL` | Address people reach `serve` at (`--public-url`). |
  372. | `BASECAMP_MCP_HTTP_REDIRECT_URI` | Basecamp Redirect URI for `serve`. Default `<public URL>/auth/callback`. |
  373. | `BASECAMP_MCP_HTTP_TOKEN` | Access key for `serve --auth key`, at least 32 characters. Created for you if missing. |
  374. | `BASECAMP_MCP_HTTP_HOST` / `BASECAMP_MCP_HTTP_PORT` | Default address for `serve` (`127.0.0.1`, `8765`). |
  375. | `BASECAMP_MCP_FULL_RESPONSES` | `1` returns full records instead of compact summaries. |
  376. ## Troubleshooting
  377. | Problem | Fix |
  378. | --- | --- |
  379. | The Basecamp tools don't appear in your app | Quit the app completely and reopen it. Check the JSON is valid. |
  380. | "spawn uvx ENOENT" or "command not found: uvx" | Desktop apps may not see your shell's PATH. Use the full path from `uvx basecamp-mcp-server config claude-desktop`. |
  381. | "Authentication required" or "token expired" | Run `uvx basecamp-mcp-server login` again. |
  382. | Login says the address is already in use | Something else is using port 8000 (often an old `oauth_app.py`). Stop it and retry. |
  383. | Login says there's no Basecamp 3 or 4 account | You signed in as a user who isn't in a Basecamp 3/4 account. Sign in with a different user. |
  384. | Basecamp shows "redirect_uri mismatch" | Your Basecamp app's Redirect URI must be exactly `http://localhost:8000/auth/callback` (or whatever `BASECAMP_REDIRECT_URI` is set to). |
  385. | 403 errors on some tools | Some Basecamp features (Lineup, account settings, timesheets) need an account admin or owner, or need the feature turned on. |
  386. Still stuck? `uvx basecamp-mcp-server status` shows where settings live and checks your sign-in. Logs are in the settings folder. Claude Desktop's own logs are in `~/Library/Logs/Claude/` (macOS) or `%APPDATA%\Claude\logs\` (Windows). Please [open an issue](https://github.com/georgeantonopoulos/Basecamp-MCP-Server/issues) with what you ran and the error.
  387. ## Run from a git checkout
  388. Use this for development, or if you'd rather not install from PyPI. A checkout keeps its settings in the repository folder, as before.
  389. ```bash
  390. git clone https://github.com/georgeantonopoulos/Basecamp-MCP-Server.git
  391. cd Basecamp-MCP-Server
  392. uv venv --python 3.12 venv
  393. source venv/bin/activate # Windows: venv\Scripts\activate
  394. uv pip install -r requirements.txt
  395. cp .env.example .env # then fill in your Basecamp app details
  396. python oauth_app.py # sign in at http://localhost:8000
  397. ```
  398. Then point your app at the checkout. These scripts write the config for you:
  399. ```bash
  400. python generate_claude_desktop_config.py # or generate_cursor_config.py, generate_codex_config.py
  401. ```
  402. Each accepts `--full` for all 210 tools, or `--legacy` for the older JSON-RPC server.
  403. Run the tests with `python -m pytest tests/`.
  404. <details>
  405. <summary><b>How the code is organised</b></summary>
  406. | File | Role |
  407. | --- | --- |
  408. | [`basecamp_mcp_server/cli.py`](basecamp_mcp_server/cli.py) | The installed command: `login`, `status`, `config` and running the server. |
  409. | [`basecamp_retrieval_mcp.py`](basecamp_retrieval_mcp.py) | Default server: four tools that discover and run the others. |
  410. | [`basecamp_tool_retrieval.py`](basecamp_tool_retrieval.py) | Categories, read/write split, and ranking for discovery. |
  411. | [`basecamp_fastmcp.py`](basecamp_fastmcp.py) | All 210 tool definitions; also the `--full` server. |
  412. | [`basecamp_client.py`](basecamp_client.py) | Basecamp API client. |
  413. | [`payload_shaping.py`](payload_shaping.py) | Compact summaries for large responses. |
  414. | [`basecamp_oauth.py`](basecamp_oauth.py), [`auth_manager.py`](auth_manager.py), [`token_storage.py`](token_storage.py) | Sign-in, automatic token refresh, and token storage. |
  415. | [`oauth_app.py`](oauth_app.py) | Browser sign-in page for git checkouts. |
  416. | [`mcp_server_cli.py`](mcp_server_cli.py) | Older JSON-RPC server, kept for compatibility. |
  417. </details>
  418. ## Security
  419. - Your Basecamp app's secret and your token stay on your machine, in files only you can read. Never commit `.env` or `oauth_tokens.json`.
  420. - Sign-in uses a one-time random check value, and the local sign-in page only accepts the response it's waiting for.
  421. - Write tools are marked as such, so MCP apps that ask before making changes will ask.
  422. - This server is built to run locally for one person. Read [the design notes](https://github.com/georgeantonopoulos/Basecamp-MCP-Server/blob/codex/central-hosting-design/CENTRAL_HOSTING_DESIGN.md) before hosting it for a team.
  423. ## License
  424. MIT. See [`LICENSE`](LICENSE).
  425. ## Star History
  426. <a href="https://www.star-history.com/#georgeantonopoulos/Basecamp-MCP-Server&Date">
  427. <picture>
  428. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=georgeantonopoulos/Basecamp-MCP-Server&type=Date&theme=dark" />
  429. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=georgeantonopoulos/Basecamp-MCP-Server&type=Date" />
  430. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=georgeantonopoulos/Basecamp-MCP-Server&type=Date" />
  431. </picture>
  432. </a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.