jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcpengine/servers/basecamp
History

README.md

Basecamp MCP Server

A comprehensive Model Context Protocol (MCP) server for Basecamp 4 API integration.

Features

  • Complete API Coverage: 50+ tools covering all major Basecamp 4 API endpoints
  • Rich UI Components: 18 React MCP apps for visualizing and managing Basecamp data
  • Robust Client: OAuth2 authentication, automatic pagination, and comprehensive error handling
  • Type-Safe: Full TypeScript implementation with detailed type definitions

Installation

npm install
npm run build

Configuration

Set the following environment variables:

export BASECAMP_ACCOUNT_ID="your-account-id"
export BASECAMP_ACCESS_TOKEN="your-oauth-token"
export BASECAMP_USER_AGENT="YourApp (your-email@example.com)"  # Optional

Getting Your Credentials

  1. Account ID: Found in your Basecamp URL: https://3.basecamp.com/{ACCOUNT_ID}/
  2. Access Token: Create an OAuth2 application at https://launchpad.37signals.com/integrations
    • Follow Basecamp's OAuth flow to get an access token
    • Scopes required: Full access to projects, todos, messages, etc.

Usage

As MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "basecamp": {
      "command": "node",
      "args": ["/path/to/basecamp-mcp/dist/main.js"],
      "env": {
        "BASECAMP_ACCOUNT_ID": "your-account-id",
        "BASECAMP_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

Standalone

npm start

Available Tools (50+)

Projects (7 tools)

  • basecamp_projects_list - List all projects
  • basecamp_project_get - Get project details
  • basecamp_project_create - Create new project
  • basecamp_project_update - Update project
  • basecamp_project_archive - Archive project
  • basecamp_project_trash - Move project to trash
  • basecamp_project_tools_list - List project tools (dock)

Todolists (5 tools)

  • basecamp_todolists_list - List todolists in project
  • basecamp_todolist_get - Get todolist details
  • basecamp_todolist_create - Create new todolist
  • basecamp_todolist_update - Update todolist
  • basecamp_todolist_reorder - Reorder todolists

Todos (8 tools)

  • basecamp_todos_list - List todos in todolist
  • basecamp_todo_get - Get todo details
  • basecamp_todo_create - Create new todo
  • basecamp_todo_update - Update todo
  • basecamp_todo_complete - Mark todo as complete
  • basecamp_todo_uncomplete - Mark todo as incomplete
  • basecamp_todos_reorder - Reorder todos

Messages (5 tools)

  • basecamp_messages_list - List messages on message board
  • basecamp_message_get - Get message details
  • basecamp_message_create - Create new message
  • basecamp_message_update - Update message
  • basecamp_message_trash - Move message to trash

Comments (4 tools)

  • basecamp_comments_list - List comments on recording
  • basecamp_comment_get - Get comment details
  • basecamp_comment_create - Create new comment
  • basecamp_comment_update - Update comment

Campfire (2 tools)

  • basecamp_campfire_lines_list - List recent chat messages
  • basecamp_campfire_line_create - Send chat message

Schedules (5 tools)

  • basecamp_schedules_list - List schedules in project
  • basecamp_schedule_entries_list - List schedule entries
  • basecamp_schedule_entry_get - Get entry details
  • basecamp_schedule_entry_create - Create new schedule entry
  • basecamp_schedule_entry_update - Update schedule entry

Documents (4 tools)

  • basecamp_documents_list - List documents in vault
  • basecamp_document_get - Get document details
  • basecamp_document_create - Create new document
  • basecamp_document_update - Update document

Uploads (3 tools)

  • basecamp_uploads_list - List uploaded files
  • basecamp_upload_get - Get upload details
  • basecamp_upload_create - Upload file

People (6 tools)

  • basecamp_people_list - List all people in account
  • basecamp_person_get - Get person details
  • basecamp_project_people_list - List people in project
  • basecamp_project_person_add - Add person to project
  • basecamp_project_person_remove - Remove person from project
  • basecamp_profile_get - Get current user profile

Questionnaires (4 tools)

  • basecamp_questionnaires_list - List automatic check-ins
  • basecamp_questionnaire_get - Get questionnaire details
  • basecamp_questions_list - List questions in questionnaire
  • basecamp_answers_list - List answers to question

Webhooks (4 tools)

  • basecamp_webhooks_list - List all webhooks
  • basecamp_webhook_create - Create new webhook
  • basecamp_webhook_update - Update webhook
  • basecamp_webhook_delete - Delete webhook

Recordings (5 tools)

  • basecamp_recordings_list - List all recordings (generic content)
  • basecamp_recording_get - Get recording details
  • basecamp_recording_archive - Archive recording
  • basecamp_recording_unarchive - Unarchive recording
  • basecamp_recording_trash - Move recording to trash

MCP Apps (18 React Components)

Project Management

  • project-dashboard - Overview of all projects with filtering
  • project-detail - Detailed single project view with dock
  • project-grid - Grid view of all projects

Task Management

  • todo-board - Kanban-style todo board
  • todo-detail - Detailed todo view with comments

Communication

  • message-board - Message board posts list
  • message-detail - Single message with comments
  • campfire-chat - Real-time team chat interface

Planning

  • schedule-calendar - Calendar view of schedule entries
  • project-timeline - Gantt-style timeline

Content

  • document-browser - Browse and manage documents
  • file-manager - File upload management

People

  • people-directory - Team member directory

Check-ins

  • checkin-dashboard - Automatic check-in overview
  • checkin-responses - View responses to check-ins

Insights

  • activity-feed - Recent project activity
  • search-results - Global search interface
  • hill-chart - Visual progress tracking

Architecture

src/
├── clients/
│   └── basecamp.ts          # API client with OAuth2 & pagination
├── tools/
│   ├── projects-tools.ts    # Project management tools
│   ├── todolists-tools.ts   # Todolist tools
│   ├── todos-tools.ts       # Todo tools
│   ├── messages-tools.ts    # Message board tools
│   ├── comments-tools.ts    # Comment tools
│   ├── campfires-tools.ts   # Chat tools
│   ├── schedules-tools.ts   # Schedule tools
│   ├── documents-tools.ts   # Document tools
│   ├── uploads-tools.ts     # File upload tools
│   ├── people-tools.ts      # People management tools
│   ├── questionnaires-tools.ts # Check-in tools
│   ├── webhooks-tools.ts    # Webhook tools
│   └── recordings-tools.ts  # Generic recordings tools
├── types/
│   └── index.ts             # TypeScript type definitions
├── ui/
│   └── react-app/
│       ├── index.tsx        # App registry
│       └── apps/            # 18 React MCP apps
├── server.ts                # MCP server implementation
└── main.ts                  # Entry point

API Reference

Basecamp 4 API

  • Base URL: https://3.basecampapi.com/{account_id}/
  • Authentication: OAuth2 Bearer token
  • Rate limiting: Respected via standard headers
  • User-Agent: Required for all requests

Error Handling

The client handles common errors:

  • 401: Invalid/expired token
  • 403: Permission denied
  • 404: Resource not found
  • 429: Rate limit exceeded
  • 500-503: Server errors

Development

Build

npm run build

Watch Mode

npm run dev

License

MIT

Contributing

Contributions welcome! Please ensure:

  • All tools have proper input validation
  • TypeScript types are comprehensive
  • Error handling is consistent
  • MCP apps are self-contained

Links