Basecamp Mcp Server

🏕️ 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](./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

[](https://workers.cloudflare.com/) [](https://modelcontextprotocol.io/) [](https://github.com/QusaiiSaleem/basecamp-mcp-server/releases) [](https://claude.ai) [](https://opensource.org/licenses/MIT)

✨ 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_token in arguments (highest priority)
2. Authorization: Bearer TOKEN header
3. BASECAMP_ACCESS_TOKEN environment 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

# 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

1. Set Environment Variables:

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

1. Visit Claude.ai: Go to claude.ai
2. Open Settings: Click Settings → Connectors
3. Add Remote MCP Server:

• Name: Basecamp MCP
• URL: https://your-worker.workers.dev
• Authentication: Bearer YOUR_ACCESS_TOKEN

1. Enable Toggle: Turn on the connector ✅
2. 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](./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):

{
  "basecamp": {
    "command": "node",
    "args": ["path/to/mcp-server"],
    "env": {
      "BASECAMP_ACCESS_TOKEN": "your_token_here",
      "BASECAMP_ACCOUNT_ID": "your_account_id"
    }
  }
}

Direct API Usage

// 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:

// 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:

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

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

# Clone the repository
git clone https://github.com/QusaiiSaleem/basecamp-mcp-server.git
cd basecamp

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [QusaiiSaleem](https://github.com/QusaiiSaleem)
- **Source:** [QusaiiSaleem/basecamp-mcp-server](https://github.com/QusaiiSaleem/basecamp-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.