Basecamp MCP Server

Basecamp MCP Server

A professional MCP server providing complete programmatic access to Basecamp 4 API for AI agents, workflow automation, and custom integrations.

Category
访问服务器

README

🏕️ 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

Deploy to Cloudflare Workers MCP Protocol Version Claude.ai Compatible License: 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

  3. 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
  4. Enable Toggle: Turn on the connector ✅
  5. Verify Tools: All 55 tools should appear in your conversation

Full Setup Guide

For detailed step-by-step instructions including screenshots and troubleshooting, see:

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

Transform your Basecamp workflow with complete API automation! 🚀

Now with full Claude.ai compatibility in v7.5! ✨

Deploy Now

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选