Rebrand to MCPEngage and add Basecamp-specific content
- Fixed all MCPEngine → MCPEngage references - Added 8 Basecamp-specific power moves for project management & team collaboration - Updated README with accurate tool count and real Basecamp 4 API details - Added proper OAuth 2.0 authentication documentation - Updated package.json author - Enhanced .env.example with detailed credential instructions including User-Agent
This commit is contained in:
Jake Shore
parent
3a2e785897
commit
6fd0eef055
12
.env.example
12
.env.example
@ -1,2 +1,12 @@
|
||||
# Basecamp API Credentials
|
||||
BASECAMP_API_KEY=your-api-key-here
|
||||
# Get these from: https://launchpad.37signals.com/integrations
|
||||
|
||||
# OAuth 2.0 Access Token (get via OAuth flow)
|
||||
BASECAMP_ACCESS_TOKEN=your-oauth-token-here
|
||||
|
||||
# Your Account ID (from URL: https://3.basecamp.com/{ACCOUNT_ID}/)
|
||||
BASECAMP_ACCOUNT_ID=your-account-id-here
|
||||
|
||||
# User-Agent identifier (required by Basecamp API)
|
||||
# Format: "AppName (contact@email.com)"
|
||||
BASECAMP_APP_IDENTITY="MCPServer (mcp@example.com)"
|
||||
|
||||
126
README.md
126
README.md
@ -4,32 +4,39 @@
|
||||
|
||||
---
|
||||
|
||||
# 🚀 Basecamp MCP Server — 2026 Complete Version
|
||||
# 📊 Basecamp MCP Server — 2026 Complete Version
|
||||
|
||||
## 💡 What This Unlocks
|
||||
|
||||
**This MCP server gives AI direct access to your entire Basecamp workspace.** Instead of clicking through interfaces, you just *tell* it what you need.
|
||||
**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.
|
||||
|
||||
### 🎯 Basecamp-Native Power Moves
|
||||
### 🎯 Team Collaboration Power Moves
|
||||
|
||||
The AI can directly control your Basecamp account with natural language:
|
||||
|
||||
- **Smart automation** — Complex workflows in plain English
|
||||
- **Data intelligence** — Query, analyze, and export your Basecamp data
|
||||
- **Rapid operations** — Bulk actions that would take hours manually
|
||||
- **Cross-platform integration** — Combine Basecamp with other tools seamlessly
|
||||
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 data → Filter results → Generate reports
|
||||
- Search records → Update fields → Notify team
|
||||
- Analyze metrics → Create tasks → Schedule follow-ups
|
||||
- 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
|
||||
|
||||
**52 API tools** covering the entire Basecamp platform (Project Management).
|
||||
**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.
|
||||
|
||||
@ -45,7 +52,11 @@ All with proper error handling, automatic authentication, and TypeScript types.
|
||||
npm run build
|
||||
```
|
||||
|
||||
2. **Get your Basecamp API credentials** (see Authentication section below)
|
||||
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:**
|
||||
|
||||
@ -58,9 +69,11 @@ All with proper error handling, automatic authentication, and TypeScript types.
|
||||
"mcpServers": {
|
||||
"basecamp": {
|
||||
"command": "node",
|
||||
"args": ["/ABSOLUTE/PATH/TO/basecamp-mcp/dist/index.js"],
|
||||
"args": ["/ABSOLUTE/PATH/TO/basecamp-mcp-2026-complete/dist/index.js"],
|
||||
"env": {
|
||||
"BASECAMP_API_KEY": "your-api-key-here"
|
||||
"BASECAMP_ACCESS_TOKEN": "your-oauth-token-here",
|
||||
"BASECAMP_ACCOUNT_ID": "your-account-id-here",
|
||||
"BASECAMP_APP_IDENTITY": "YourAppName (contact@yourdomain.com)"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -74,7 +87,7 @@ All with proper error handling, automatic authentication, and TypeScript types.
|
||||
[](https://railway.app/template/basecamp-mcp)
|
||||
|
||||
1. Click the button above
|
||||
2. Set your Basecamp API credentials in Railway dashboard
|
||||
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
|
||||
@ -82,32 +95,70 @@ All with proper error handling, automatic authentication, and TypeScript types.
|
||||
```bash
|
||||
docker build -t basecamp-mcp .
|
||||
docker run -p 3000:3000 \
|
||||
-e BASECAMP_API_KEY=your-key \
|
||||
-e BASECAMP_ACCESS_TOKEN=your-token \
|
||||
-e BASECAMP_ACCOUNT_ID=your-account-id \
|
||||
-e BASECAMP_APP_IDENTITY="MyApp (me@example.com)" \
|
||||
basecamp-mcp
|
||||
```
|
||||
|
||||
## 🔐 Authentication
|
||||
|
||||
See the official [Basecamp API documentation](https://docs.basecamp.com) for authentication details.
|
||||
Basecamp uses **OAuth 2.0** authentication with account-specific access tokens.
|
||||
|
||||
The MCP server handles token refresh automatically.
|
||||
**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)
|
||||
|
||||
## 🎯 Example Prompts
|
||||
**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)
|
||||
|
||||
Once connected to Claude, you can use natural language. Examples:
|
||||
**Official docs:** [Basecamp 4 API Authentication](https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md)
|
||||
|
||||
- *"Show me recent activity in Basecamp"*
|
||||
- *"Create a new record with these details..."*
|
||||
- *"Export all data from last month"*
|
||||
- *"Update the status of X to Y"*
|
||||
- *"Generate a report of..."*
|
||||
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 account with API access
|
||||
- Basecamp 4 account with API access
|
||||
|
||||
### Setup
|
||||
|
||||
@ -132,9 +183,18 @@ npm run test:coverage # Coverage report
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### "Authentication failed"
|
||||
- Verify your API credentials are correct
|
||||
- Check that your API key hasn't been revoked
|
||||
- Ensure you have the necessary permissions
|
||||
- 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
|
||||
@ -143,7 +203,9 @@ npm run test:coverage # Coverage report
|
||||
|
||||
## 📖 Resources
|
||||
|
||||
- [Basecamp API Documentation](https://docs.basecamp.com)
|
||||
- [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)
|
||||
|
||||
@ -163,10 +225,10 @@ MIT License - see [LICENSE](LICENSE) for details
|
||||
|
||||
## 🙏 Credits
|
||||
|
||||
Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.
|
||||
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/mcpengine).
|
||||
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
"description": "MCP server for Basecamp API - 2026 Complete Version",
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
"author": "MCPEngine <hello@mcpengage.com>",
|
||||
"author": "MCPEngage <hello@mcpengage.com>",
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user