# ActiveCollab MCP Server
Local MCP (Model Context Protocol) server for ActiveCollab API integration. Allows Claude Code to access ActiveCollab data without exposing API tokens to external services.
## Architecture
```
Claude Code (CLI)
│
▼
┌──────────────────┐
│ MCP Server │ ← Python, runs locally
│ (stdio) │
└──────────────────┘
│
▼
┌──────────────────┐
│ ActiveCollab API │ ← HTTPS
└──────────────────┘
```
## Requirements
- Python 3.8+
- pip
## Setup
### 1. Ensure Python is available
On some Linux distributions, `python` command may not exist (only `python3`). Fix with:
```bash
# Ubuntu/Debian (recommended)
sudo apt install python-is-python3
# Or manually create symlink
sudo ln -s /usr/bin/python3 /usr/bin/python
```
### 2. Install dependencies
```bash
pip install -r requirements.txt
```
### 3. Generate API token
Run the token generator script:
```bash
python generate_token.py
```
The script will prompt you for:
- **ActiveCollab URL** - Your self-hosted instance URL (e.g., `https://collab.yourcompany.com`)
- **Email** - Your ActiveCollab login email
- **Password** - Your ActiveCollab password (hidden input)
```
=== ActiveCollab API Token Generator (Self-Hosted) ===
ActiveCollab URL (e.g., https://collab.inchoo.net): https://collab.yourcompany.com
Email: your.email@company.com
Password: ********
Generating token...
==================================================
SUCCESS! Here are your credentials:
API URL: https://collab.yourcompany.com/api/v1
API Token: 1-aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789
==================================================
Save to config.json now? (y/n): y
Saved to config.json!
```
**How it works:**
1. Makes a POST request to `/api/v1/issue-token` with your credentials
2. ActiveCollab returns a permanent API token for the "Claude MCP Server" client
3. Token is saved to `config.json`
**Alternative:** Manually create config.json:
```bash
cp config.json.example config.json
# Edit config.json with your API URL and token
```
### 4. Configure MCP server
```bash
cp .mcp.json.example .mcp.json
# Edit .mcp.json - update "cwd" to your absolute path
```
### 5. Restart Claude Code
## Available Tools
| Tool | Parameters | Description |
|------|------------|-------------|
| `list_projects` | - | List all projects |
| `get_project` | `project_id` | Get project details |
| `list_tasks` | `project_id`, `status` (all/open/completed) | List tasks for a project |
| `get_task` | `project_id`, `task_id` | Get task details |
| `my_tasks` | - | Get tasks assigned to current user |
| `get_task_comments` | `task_id` | Get comments on a task |
| `get_task_time_records` | `project_id`, `task_id` | Get time records for a task |
| `get_project_time_records` | `project_id` | Get all time records for a project |
| `get_notifications` | - | Get recent notifications for current user |
| `get_subtasks` | `project_id`, `task_id` | Get subtasks for a task |
| `get_overdue_tasks` | `project_id` | Get tasks with overdue deadlines |
| `get_tasks_with_deadlines` | `project_id` | Get open tasks sorted by due date |
| `get_labels` | - | Get all global task labels |
| `get_tasks_by_label` | `project_id`, `label_id` | Get tasks with specific label |
| `get_task_lists` | `project_id` | Get all task lists in a project |
| `get_tasks_by_list` | `project_id`, `task_list_id` | Get tasks in a specific list |
| `get_users` | - | Get all team members (not clients) |
| `get_tasks_by_assignee` | `project_id`, `user_id` | Get tasks assigned to a user |
## Usage Examples
```
> List all projects
> Show open tasks for project 5
> Get details of task 123
> Show my tasks
> Get comments for task 456
> Show time records for task 61735 in project 489
> Get all time records for project 489
> Show my notifications
> Get subtasks for task 61735 in project 489
> Show overdue tasks for project 489
> Show tasks with deadlines for project 489
> List all labels
> Show tasks with STORY label (272) in project 489
> Show task lists for project 489
> Show tasks in IN PROGRESS list (31231) for project 489
> List all team members
> Show tasks assigned to Željko (1090) in project 489
```
## Project Structure
```
activeMCP/
├── src/
│ ├── __init__.py
│ ├── server.py # MCP server with tool definitions
│ ├── api/
│ │ ├── __init__.py
│ │ └── client.py # ActiveCollab API client
│ └── utils/
│ ├── __init__.py
│ └── config.py # Configuration loader
├── generate_token.py # API token generator script
├── config.json # API credentials (gitignored)
├── config.json.example # Template for config.json
├── .mcp.json # MCP server config (gitignored)
├── .mcp.json.example # Template for .mcp.json
├── run_server.sh # Server launcher script
├── requirements.txt
└── README.md
```
## Dependencies
- Python 3.8+ (ensure `python` command is available, see Setup step 1)
- `mcp>=1.0.0` - Model Context Protocol SDK
- `httpx>=0.25.0` - HTTP client (optional, using urllib)
## Implementation Status
- [x] Phase 1: Basic infrastructure (config, client, auth)
- [x] Phase 2: MCP server skeleton
- [x] Phase 3: Projects module (list, get)
- [x] Phase 4: Tasks module (list, get, filter by status)
- [x] Phase 5: Time tracking module (read only)
- [x] Phase 6: Comments module (read only)
- [x] Phase 7: Notifications module (read only)
- [x] Phase 8: Subtasks module (read only)
- [x] Phase 9: Deadlines module (overdue tasks, tasks with deadlines)
- [x] Phase 10: Labels module (list labels, filter tasks by label)
- [x] Phase 11: Task lists module (list task lists, filter tasks by list)
- [x] Phase 12: Users module (list users, filter tasks by assignee)
- [ ] Phase 13: Write operations (create/update tasks, add comments, log time)
