🏕️ Basecamp MCP Server
A professional Model Context Protocol (MCP) server that provides complete programmatic access to Basecamp 4 API. Perfect for AI agents, workflow automation, and custom integrations.
🚀 NEW in v7.5.0: Claude.ai Compatible!
The most comprehensive AND most compatible Basecamp MCP server available!
What's New in v7.5:
- ✅ Full Claude.ai compatibility - Works perfectly in Claude web interface
- ✅ Latest MCP protocol - Supports 2025-06-18 specification
- ✅ Session management - Proper connection tracking for modern clients
- ✅ Auto-discovery - MCP config endpoint for automatic setup
- ✅ Simplified authentication - No KV storage, just OAuth + environment variables
- ✅ 55+ specialized tools - Complete Basecamp API coverage
🔥 Upgrade from v6.0? See UPGRADE-TO-V75.md for migration guide.
✅ 8 Project Management tools - Complete project lifecycle management
✅ 11 Todo Management tools - Advanced task automation with auto-lookup
✅ 6 Communication tools - Messages and discussions
✅ 6 Documents & Files tools - Content management and file handling
✅ 4 Team Management tools - Access control and permissions
✅ 3 Campfire Chat tools - Real-time communication
✅ 3 Schedule Management tools - Calendar and events
✅ 4 Card Tables tools - Kanban workflows
✅ 5 Comments System tools - Universal collaboration
✅ 4 Webhooks tools - Real-time notifications
✅ 2 Search & Analytics tools - Data insights
🆕 3 Enhanced Features - Auto-lookup, URL parsing, OAuth flow
Enhanced Features:
- Auto-lookup functionality - No more 404 errors! Automatically finds resource IDs
- OAuth 2.0 integration - Complete authentication flow with setup UI
- Multiple authentication methods - Bearer token, arguments, environment variables
- Production-ready deployment - Cloudflare Workers optimized
✨ Features
🛠️ Complete Tool Coverage (59 Tools)
- Project Management (8 tools): Full CRUD operations, archiving, construction
- Todo Management (11 tools): Lists, items, assignments, completion, positioning
- Communication (6 tools): Messages, replies, discussions, archiving
- Documents & Files (6 tools): Create, edit, upload, manage attachments
- Team Management (4 tools): Add/remove people, permissions, access control
- Comments & Collaboration (5 tools): Universal commenting system across all content
- Campfire Chat (3 tools): Real-time chat messages and history
- Schedule Management (3 tools): Events, milestones, calendar entries
- Card Tables (4 tools): Kanban boards, cards, columns, positioning
- Webhooks (4 tools): Real-time notifications and event subscriptions
- Search & Analytics (2 tools): Content search and activity tracking
🔐 Authentication & Security
- OAuth 2.0 complete authentication flow with setup UI
- Multi-authentication support with token priorities:
1.access_tokenin arguments (highest priority)
2.Authorization: Bearer TOKENheader
3.BASECAMP_ACCESS_TOKENenvironment variable (fallback) - Individual user tokens while sharing infrastructure
- Secure token handling with proper validation
- Simplified deployment - No KV storage required (v7.5+)
🚀 Production Ready
- Edge deployment on Cloudflare Workers
- Global CDN with sub-100ms response times worldwide
- Automatic scaling handles any traffic volume
- Rate limiting compliance with Basecamp API limits
- Comprehensive error handling with meaningful messages
- Auto-lookup functionality prevents 404 errors
🚀 Quick Start
1. Deploy to Cloudflare Workers```bash
Clone the repository
git clone https://github.com/QusaiiSaleem/basecamp-mcp-server.git
cd basecamp-mcp-server
Install dependencies
npm install
Configure your environment
cp wrangler.toml.example wrangler.toml
Edit wrangler.toml with your account ID
Deploy to Cloudflare Workers
npm run deploy
### 2. Set Up Basecamp OAuth Integration
1. **Create Integration**: Visit Basecamp Integrations
2. **Configure Settings**:
- **Application Name**: "Your Basecamp MCP Server"
- **Redirect URI**: `https://your-worker.workers.dev/auth/callback`
- **Client Type**: Web Application
3. **Set Environment Variables**:```bash
echo "your_client_id" | wrangler secret put BASECAMP_CLIENT_ID
echo "your_client_secret" | wrangler secret put BASECAMP_CLIENT_SECRET
echo "your_account_id" | wrangler secret put BASECAMP_ACCOUNT_ID
3. Get Your Access Token
Visit https://your-worker.workers.dev/setup and follow the OAuth flow to get your access token.
🌐 Claude.ai Integration
NEW in v7.5: Direct integration with Claude.ai web interface!
Quick Setup
- Visit Claude.ai: Go to claude.ai
- Open Settings: Click Settings → Connectors
- Add Remote MCP Server:
- Name:Basecamp MCP
- URL:https://your-worker.workers.dev
- Authentication:Bearer YOUR_ACCESS_TOKEN - Enable Toggle: Turn on the connector ✅
- Verify Tools: All 55 tools should appear in your conversation
Full Setup Guide
For detailed step-by-step instructions including screenshots and troubleshooting, see:
- CLAUDE-AI-SETUP.md - Complete integration guide
Test Your Connection
In Claude.ai, try these commands:```
"List all my Basecamp projects"
"Show me my current todo assignments"
"Create a new message in Project X"
### Compatibility Matrix
| Client | v6.0 | v7.5 |
|--------|------|------|
| Claude.ai | ⚠️ Limited | ✅ Full |
| Claude Desktop | ✅ Works | ✅ Works |
| Smithery Playground | ⚠️ Limited | ✅ Full |
| RelevanceAI | ✅ Works | ✅ Works |
| n8n | ✅ Works | ✅ Works |
| Make.com | ✅ Works | ✅ Works |
## 🔧 Usage Examples
### With RelevanceAI
1. **Agent Settings** → **MCP Server** → **Add remote MCP tools**
2. **Server URL**: `https://your-worker.workers.dev`
3. **Authentication**: `Bearer your_access_token_here`
### With Claude Desktop
Add to your MCP configuration (`~/.claude/mcp_servers.json`):```json
{
"basecamp": {
"command": "node",
"args": ["path/to/mcp-server"],
"env": {
"BASECAMP_ACCESS_TOKEN": "your_token_here",
"BASECAMP_ACCOUNT_ID": "your_account_id"
}
}
}
Direct API Usage```javascript
// Enhanced auto-lookup - no more resource ID hunting!
{
"tool": "get_todo_lists",
"arguments": {
"project_id": "123456" // That's it! Auto-finds todoset ID
}
}
// Create todos with full assignment control
{
"tool": "create_todo",
"arguments": {
"project_id": "123456",
"todolist_id": "789012",
"content": "Complete project setup",
"due_on": "2024-12-31",
"assignee_ids": [1001, 1002]
}
}
// Universal commenting system
{
"tool": "add_comment_to_recording",
"arguments": {
"project_id": "123456",
"recording_id": "789012", // Works with any content type
"content": "Great progress on this item!"
}
}
// Smart URL parsing
{
"tool": "parse_basecamp_url",
"arguments": {
"url": "https://3.basecamp.com/999999/buckets/123456/todolists/789012"
}
}
## 📚 Complete Tool Reference
### 📋 Project Management (8 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_projects` | List all accessible projects | - |
| `create_project` | Create new project | `name`, `description` |
| `get_project` | Get project details | `project_id` |
| `update_project` | Update project info | `project_id`, `name`, `description` |
| `archive_project` | Archive project | `project_id` |
| `unarchive_project` | Unarchive project | `project_id` |
| `get_project_construction` | Get project tools/features | `project_id` |
| `parse_basecamp_url` | Parse any Basecamp URL | `url` |
### ✅ Todo Management (11 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_todo_lists` 🚀 | Get todo lists (AUTO-LOOKUP) | `project_id` |
| `create_todo_list` 🚀 | Create todo list (AUTO-LOOKUP) | `project_id`, `name` |
| `get_todos` | Get todos from list | `project_id`, `todolist_id` |
| `get_all_project_todos` 🆕 | Get ALL project todos | `project_id` |
| `create_todo` | Create new todo | `project_id`, `todolist_id`, `content` |
| `update_todo` | Update todo details | `project_id`, `todo_id`, `content` |
| `complete_todo` | Mark todo complete | `project_id`, `todo_id` |
| `uncomplete_todo` | Mark todo incomplete | `project_id`, `todo_id` |
| `get_my_assignments` | Get current user assignments | - |
| `get_user_assignments` | Get user's assignments | `user_id` |
| `reposition_todo` | Change todo position | `project_id`, `todo_id`, `position` |
### 💬 Communication (6 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_message_board` 🚀 | Get message board (AUTO-LOOKUP) | `project_id` |
| `get_messages` 🚀 | Get messages (AUTO-LOOKUP) | `project_id` |
| `create_message` 🚀 | Create message (AUTO-LOOKUP) | `project_id`, `subject`, `content` |
| `update_message` | Edit message | `project_id`, `message_id`, `content` |
| `get_message` | Get specific message | `project_id`, `message_id` |
| `archive_message` | Archive message | `project_id`, `message_id` |
### 📄 Documents & Files (6 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_documents` 🚀 | List documents (AUTO-LOOKUP) | `project_id` |
| `create_document` 🚀 | Create document (AUTO-LOOKUP) | `project_id`, `title`, `content` |
| `update_document` | Edit document | `project_id`, `document_id`, `content` |
| `get_document` | Get specific document | `project_id`, `document_id` |
| `upload_attachment` | Upload file | `file_data`, `filename`, `content_type` |
| `get_uploads` | List project uploads | `project_id` |
### 👥 Team & People (4 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_people` | Get project team | `project_id` |
| `get_all_people` | Get all account people | - |
| `add_person_to_project` | Grant project access | `project_id`, `person_ids[]` |
| `remove_person_from_project` | Revoke project access | `project_id`, `person_ids[]` |
### 💭 Comments & Collaboration (5 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `add_comment_to_recording` | Universal comment tool | `project_id`, `recording_id`, `content` |
| `add_comment_to_todo` | Comment on todo | `project_id`, `todo_id`, `content` |
| `add_comment_to_message` | Reply to message | `project_id`, `message_id`, `content` |
| `add_comment_to_document` | Comment on document | `project_id`, `document_id`, `content` |
| `add_comment_to_card` | Comment on card | `project_id`, `card_id`, `content` |
### 💬 Campfire Chat (3 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_campfire` | Get project chat | `project_id` |
| `get_campfire_lines` | Get chat messages | `project_id`, `campfire_id` |
| `post_campfire_message` | Post chat message | `project_id`, `campfire_id`, `content` |
### 📅 Schedule Management (3 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_schedule` 🚀 | Get schedule (AUTO-LOOKUP) | `project_id` |
| `get_schedule_entries` | Get schedule events | `project_id` |
| `create_schedule_entry` | Create new event | `project_id`, `summary`, `starts_at` |
### 🎫 Card Tables (4 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_card_table` | Get Kanban board | `project_id` |
| `get_cards` | Get cards from table | `project_id`, `card_table_id` |
| `create_card` | Create new card | `project_id`, `card_table_id`, `title` |
| `update_card` | Update existing card | `project_id`, `card_id`, `title` |
### 🔗 Webhooks (4 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_webhooks` | List all webhooks | - |
| `create_webhook` | Create webhook | `payload_url`, `types[]` |
| `update_webhook` | Update webhook | `webhook_id`, `payload_url` |
| `delete_webhook` | Delete webhook | `webhook_id` |
### 🔍 Search & Analytics (2 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `search` | Search content | `query`, `project_id` (optional) |
| `get_events` | Get activity/events | `project_id` (optional) |
## 🔍 Smart Features
### 🧠 Auto-Lookup Intelligence
The server automatically finds required resource IDs, eliminating 404 errors:```javascript
// Before: Complex resource ID hunting
{
"tool": "get_todo_lists",
"arguments": {
"project_id": "123456",
"todoset_id": "789012" // ← Hard to find manually
}
}
// After: Simple auto-lookup
{
"tool": "get_todo_lists",
"arguments": {
"project_id": "123456" // ← Auto-finds todoset ID
}
}
📈 URL Intelligence
Parse any Basecamp URL to extract project and resource information:```javascript
// Input: https://3.basecamp.com/999999/buckets/123456/todolists/789012
// Output:
{
"account_id": "999999",
"project_id": "123456",
"resource_type": "todolists",
"resource_id": "789012",
"suggested_tools": ["get_todos", "create_todo"]
}
### 🔄 Multi-Authentication Support
Flexible authentication with priority order:
1. **Arguments**: `access_token` parameter (highest priority)
2. **Headers**: `Authorization: Bearer TOKEN`
3. **Environment**: `BASECAMP_ACCESS_TOKEN` (fallback)
## ⚙️ Configuration
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `BASECAMP_ACCOUNT_ID` | Your Basecamp account ID | ✅ |
| `BASECAMP_CLIENT_ID` | OAuth client ID | ✅ (for OAuth) |
| `BASECAMP_CLIENT_SECRET` | OAuth client secret | ✅ (for OAuth) |
| `BASECAMP_ACCESS_TOKEN` | Fallback access token | ⚠️ (optional) |
### wrangler.toml Example```toml
name = "my-basecamp-mcp-server"
main = "index.ts"
compatibility_date = "2024-08-05"
[vars]
BASECAMP_ACCOUNT_ID = "999999999"
# Note: v7.5 no longer requires KV namespace binding
# All authentication is handled via environment variables
🔒 Security Best Practices
Authentication Security
- Individual Tokens: Each user maintains their own OAuth token
- Secure Headers: All requests use proper authorization headers
- Token Validation: Automatic token validation and error handling
- Environment Isolation: Production secrets separate from code
API Security
- Rate Limiting: Automatic compliance with Basecamp API limits
- Request Validation: Input sanitization and type checking
- Error Handling: Secure error messages without data leaks
- CORS Configuration: Proper cross-origin resource sharing
🚀 Deployment Options
Cloudflare Workers (Recommended)
- Global Edge Network: Sub-100ms response times worldwide
- Automatic Scaling: Handle unlimited traffic
- Built-in Security: DDoS protection, WAF, SSL
- Cost Effective: Pay per request, no idle costs
Alternative Platforms
- Vercel Functions: Serverless deployment
- AWS Lambda: Enterprise-grade infrastructure
- Google Cloud Functions: Google ecosystem integration
- Azure Functions: Microsoft ecosystem integration
Self-Hosted Options
- Node.js Server: Traditional server deployment
- Docker Container: Containerized deployment
- Kubernetes: Container orchestration
🤝 Contributing
We welcome contributions! Here's how to get started:
Development Setup```bash
Clone the repository
git clone https://github.com/QusaiiSaleem/basecamp-mcp-server.git
cd basecamp-mcp-server
Install dependencies
npm install
Set up environment
cp wrangler.toml.example wrangler.toml
Start development server
npm run dev
### Adding New Tools
1. **Define Tool Schema**: Add tool definition to `getAllBasecampTools()`
2. **Implement Handler**: Add case to `callBasecampTool()` switch statement
3. **Test Implementation**: Verify with Basecamp API endpoints
4. **Update Documentation**: Add to README tool reference
5. **Submit Pull Request**: Include tests and examples
## 📊 Performance & Monitoring
### Performance Metrics
- **Response Time**: Average <100ms globally
- **Availability**: 99.9% uptime SLA
- **Throughput**: 10,000+ requests per second capability
- **Error Rate**: <0.1% error rate
### Monitoring Features
- **Cloudflare Analytics**: Request metrics and performance
- **Custom Logging**: Detailed operation tracking
- **Error Reporting**: Automated error notifications
- **Health Checks**: Continuous availability monitoring
## ❓ Troubleshooting
### Common Issues
#### Authentication Errors```
Error: Authentication required
Solution: Ensure your access token is valid. Visit /setup for OAuth flow.
Configuration Missing```
Error: BASECAMP_ACCESS_TOKEN not configured
**Solution**: Set up OAuth credentials or provide token in request headers.
#### Auto-lookup Failures```
Error: Todo lists are not enabled for this project
Solution: Enable todo lists in your Basecamp project settings.
Getting Help
- GitHub Issues: Report bugs and request features
- Discussions: Community support and questions
- Documentation: Comprehensive guides and examples
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🏆 Acknowledgments
- Basecamp Team: For providing an excellent API
- MCP Community: For the Model Context Protocol standard
- Cloudflare: For the edge computing platform
- Contributors: Thank you to all contributors!
📋 Version History
- v7.5.0 (2025-09-30): Claude.ai compatibility + protocol updates - CHANGELOG.md
- v6.0.0 (2024-12-15): Complete 59-tool implementation
- v5.0.0 (2024-10-01): Initial public release
🔗 Links
- 🏠 Homepage: GitHub Repository
- 📖 Documentation: Complete API Reference
- 🚀 Upgrade Guide: UPGRADE-TO-V75.md
- 📝 Changelog: CHANGELOG.md
- 🤖 Claude.ai Setup: CLAUDE-AI-SETUP.md
- 🐛 Issues: Bug Reports
- 💬 Discussions: Community Forum
- 🏕️ Basecamp API: Official Documentation
- 🤖 MCP Protocol: Specification
Transform your Basecamp workflow with complete API automation! 🚀
Now with full Claude.ai compatibility in v7.5! ✨
