basecamp-mcp-2026-complete/README.md

> **🚀 Don't want to self-host?** [Join the waitlist for our fully managed solution →](https://mcpengage.com/basecamp)
> 
> 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:**
   ```bash
   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](https://launchpad.37signals.com/integrations)
   - 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`

   ```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

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/basecamp-mcp)

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

```bash
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](https://launchpad.37signals.com/integrations)
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](https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md)

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

```bash
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

```bash
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](https://github.com/basecamp/bc3-api)
- [Basecamp Launchpad (OAuth Setup)](https://launchpad.37signals.com/integrations)
- [Authentication Guide](https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)

## 🤝 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](LICENSE) for details

## 🙏 Credits

Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software.

Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.

---

**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).