basecamp-mcp-2026-complete/README.md

🚀 Don't want to self-host? Join the waitlist for our fully managed solution →

Zero setup. Zero maintenance. Just connect and automate.

---

📊 Basecamp MCP Server — 2026 Complete Version

💡 What This Unlocks

This MCP server gives AI direct access to your Basecamp workspace. Instead of manually clicking through projects and to-dos, you just tell the AI what you need.

🎯 Team Collaboration Power Moves

The AI can directly control your Basecamp account with natural language:

1. Project Intelligence — "Show me all active projects" or "Get full details on the Q1 Launch project including tools and team"
2. Smart Task Management — "List all incomplete to-dos in the Engineering project" or "Create 5 new tasks for the design sprint with due dates"
3. Instant Updates — "Post a message to the Marketing project board about today's campaign results"
4. Team Coordination — "List all team members in the Q2 Planning project" or "Show me who's assigned to incomplete tasks"
5. Bulk Operations — "Mark all overdue to-dos as complete" or "Create to-dos from a list of requirements"

🔗 The Real Power: Combining Tools

AI can chain multiple Basecamp operations together:

• Query projects → List to-dos → Identify blockers → Post status update
• Pull team members → Check task assignments → Balance workload
• Analyze completed tasks → Generate progress report → Share with stakeholders
• Create to-dos from meeting notes → Assign team members → Set deadlines

📦 What's Inside

8 powerful API tools covering core Basecamp operations:

• Projects: list_projects, get_project
• To-Dos: list_todos, create_todo, complete_todo
• Messages: list_messages, create_message
• People: list_people

All with proper error handling, automatic authentication, and TypeScript types.

🚀 Quick Start

Option 1: Claude Desktop (Local)

1. Clone and build:

   git clone https://github.com/BusyBee3333/Basecamp-MCP-2026-Complete.git
   cd basecamp-mcp-2026-complete
   npm install
   npm run build
   

2. Get your Basecamp API credentials:

   • Go to Basecamp Launchpad
   • Create a new OAuth 2.0 app (or use existing)
   • Complete the OAuth flow to get an access token
   • Find your Account ID in your Basecamp URL: https://3.basecamp.com/{ACCOUNT_ID}/

3. Configure Claude Desktop:

   On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   On Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "basecamp": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/basecamp-mcp-2026-complete/dist/index.js"],
         "env": {
           "BASECAMP_ACCESS_TOKEN": "your-oauth-token-here",
           "BASECAMP_ACCOUNT_ID": "your-account-id-here",
           "BASECAMP_APP_IDENTITY": "YourAppName (contact@yourdomain.com)"
         }
       }
     }
   }
   

4. Restart Claude Desktop

Option 2: Deploy to Railway

1. Click the button above
2. Set BASECAMP_ACCESS_TOKEN, BASECAMP_ACCOUNT_ID, and BASECAMP_APP_IDENTITY in Railway dashboard
3. Use the Railway URL as your MCP server endpoint

Option 3: Docker

docker build -t basecamp-mcp .
docker run -p 3000:3000 \
  -e BASECAMP_ACCESS_TOKEN=your-token \
  -e BASECAMP_ACCOUNT_ID=your-account-id \
  -e BASECAMP_APP_IDENTITY="MyApp (me@example.com)" \
  basecamp-mcp

🔐 Authentication

Basecamp uses OAuth 2.0 authentication with account-specific access tokens.

Required credentials:

• BASECAMP_ACCESS_TOKEN — OAuth 2.0 access token from Basecamp Launchpad
• BASECAMP_ACCOUNT_ID — Your account ID (from URL: https://3.basecamp.com/{ACCOUNT_ID}/)
• BASECAMP_APP_IDENTITY — User-Agent identifier: "AppName (contact@email.com)" (required by Basecamp API)

Setting up OAuth 2.0:

1. Visit Basecamp Launchpad
2. Register your application
3. Complete the OAuth flow to get an access token
4. Store the token securely (it doesn't expire but can be revoked)

Official docs: Basecamp 4 API Authentication

The MCP server handles API routing and authentication headers automatically.

🎯 Example Prompts for Claude

Once connected, you can use natural language to manage your projects:

Project Management:

• "Show me all active projects"
• "Get details for the Q1 Launch project including all tools and team members"
• "List archived projects from last year"

Task Management:

• "Show me all incomplete to-dos in the Engineering project"
• "Create a new to-do: 'Review design mockups' in the Design to-do list, assign to Sarah, due Friday"
• "Mark to-do #12345 as complete"
• "List all overdue tasks across all projects"

Team Communication:

• "Post a message to the Marketing project board: 'Campaign launched successfully, tracking metrics'"
• "List recent messages in the Product Development project"
• "Create an announcement about tomorrow's team meeting"

Team Coordination:

• "Show me all people in the Q2 Planning project"
• "List all team members across the account"
• "Find who's assigned to incomplete tasks in Engineering"

Bulk Operations:

• "Create 10 to-dos from this requirements list and assign them to different team members"
• "Generate a project status report by pulling all completed tasks from last week"

Combined Operations:

• "Check all projects → identify incomplete to-dos → post a summary message to each project"
• "Pull team members → analyze task distribution → suggest workload rebalancing"

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn
• Basecamp 4 account with API access

Setup

git clone https://github.com/BusyBee3333/Basecamp-MCP-2026-Complete.git
cd basecamp-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env with your Basecamp credentials
npm run build
npm start

Testing

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report

🐛 Troubleshooting

"Authentication failed"

• Verify your OAuth access token is valid
• Check that your Account ID matches your Basecamp URL
• Ensure your token hasn't been revoked (check Launchpad)

"Missing User-Agent"

• Basecamp requires a User-Agent header in format: "AppName (contact@email.com)"
• Set BASECAMP_APP_IDENTITY environment variable with your app details

"Project/To-Do list not found"

• Use list_projects to get valid project IDs
• Use get_project to find to-do list IDs in the project's "dock"
• IDs are numeric; ensure you're passing numbers, not strings

"Tools not appearing in Claude"

• Restart Claude Desktop after updating config
• Check that the path in claude_desktop_config.json is absolute
• Verify the build completed successfully (dist/index.js exists)

📖 Resources

• Basecamp 4 API Documentation
• Basecamp Launchpad (OAuth Setup)
• Authentication Guide
• MCP Protocol Specification
• Claude Desktop Documentation

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-tool)
3. Commit your changes (git commit -m 'Add amazing tool')
4. Push to the branch (git push origin feature/amazing-tool)
5. Open a Pull Request

📄 License

MIT License - see LICENSE for details

🙏 Credits

Built by MCPEngage — AI infrastructure for business software.

Want more MCP servers? Check out our full catalog covering 30+ business platforms.

---

Questions? Open an issue or join our Discord community.