npm package: @jtmeunier87/teamwork-mcp
Description: MCP server for the Teamwork.com REST API — full project management control via Model Context Protocol
Author: jtmeunier87
Latest version: 1.3.5

# teamwork-mcp

MCP server for the [Teamwork.com](https://www.teamwork.com) REST API — full project management control via Model Context Protocol.

**82 tools** across 22 domains: projects, tasks, task lists, people, companies, milestones, time tracking, comments, notebooks, messages, files, risks, links, calendar, expenses, categories, tags, custom fields, webhooks, job roles, timezones, and account info.

## Requirements

- Node.js 18+
- A Teamwork.com account with an API token

## Getting Your API Token

1. Log in to Teamwork
2. Click your avatar → **Edit My Profile**
3. Go to the **API & Mobile** tab
4. Copy your API token

## Installation

### From npm

```bash
npm install -g @jtmeunier87/teamwork-mcp
```

### From source

```bash
git clone https://github.com/jtmeunier87/teamwork-mcp.git
cd teamwork-mcp
npm install
npm run build
```

## Configuration

Set environment variables:

| Variable | Required | Description |
|---|---|---|
| `TW_DOMAIN` | Yes | Your Teamwork subdomain (e.g. `mycompany` for `mycompany.teamwork.com`) |
| `TW_API_TOKEN` | Recommended | API token from your Teamwork profile |
| `TW_USERNAME` | Fallback | Teamwork login email (used with `TW_PASSWORD`) |
| `TW_PASSWORD` | Fallback | Teamwork login password |

API token auth is recommended. Username/password auth is supported as a fallback.

## Usage

### Claude Desktop / Perplexity Computer

Add to your MCP config (`claude_desktop_config.json` or equivalent):

```json
{
  "mcpServers": {
    "teamwork": {
      "command": "node",
      "args": ["/path/to/teamwork-mcp/dist/index.js"],
      "env": {
        "TW_DOMAIN": "mycompany",
        "TW_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

If installed globally via npm:

```json
{
  "mcpServers": {
    "teamwork": {
      "command": "teamwork-mcp",
      "env": {
        "TW_DOMAIN": "mycompany",
        "TW_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### Direct

```bash
TW_DOMAIN=mycompany TW_API_TOKEN=your-token node dist/index.js
```

## Tools

### Account (2)
- `get_account` — Account details (plan, URL, company info, limits)
- `get_me` — Authenticated user profile

### Projects (5)
- `get_projects` — List all projects with filtering and pagination
- `get_project_by_id` — Get a single project
- `create_project` — Create a new project
- `update_project` — Update a project
- `delete_project` — Delete a project

### Task Lists (3)
- `get_tasklists` — List all task lists
- `get_tasklists_by_project` — Task lists for a project
- `create_tasklist` — Create a task list in a project

### Tasks (13)
- `get_tasks` — List tasks with filtering (status, assignee, dates, priority, tags)
- `get_tasks_by_project` — Tasks for a project
- `get_tasks_by_tasklist` — Tasks in a task list
- `get_task_by_id` — Get a single task
- `create_task` — Create a task in a task list
- `create_subtask` — Create a subtask under a parent task
- `update_task` — Update a task
- `complete_task` — Mark task complete
- `uncomplete_task` — Reopen a completed task
- `delete_task` — Delete a task
- `get_subtasks` — Get subtasks of a parent
- `get_task_metrics_complete` — Count of completed tasks
- `get_task_metrics_late` — Count of overdue tasks

### Comments (4)
- `get_task_comments` — Comments on a task
- `get_project_comments` — Comments on a project
- `create_task_comment` — Add comment to a task
- `create_project_comment` — Add comment to a project

### People (6)
- `get_people` — List all people
- `get_person_by_id` — Get a single person
- `get_project_people` — People assigned to a project
- `add_people_to_project` — Add people to a project
- `update_person` — Update a person
- `delete_person` — Delete a person

### Companies (5)
- `get_companies` — List all companies
- `get_company_by_id` — Get a single company
- `create_company` — Create a company
- `update_company` — Update a company
- `delete_company` — Delete a company

### Milestones (6)
- `get_milestones` — List all milestones
- `get_milestones_by_project` — Milestones for a project
- `create_milestone` — Create a milestone
- `update_milestone` — Update a milestone
- `complete_milestone` — Mark milestone complete
- `delete_milestone` — Delete a milestone

### Time Tracking (7)
- `get_time_entries` — List all time entries with filtering
- `get_time_entries_by_project` — Time entries for a project
- `get_time_entries_by_task` — Time entries for a task
- `get_timers` — List active timers
- `log_time` — Log time to a task
- `update_time_entry` — Update a time entry
- `delete_time_entry` — Delete a time entry

### Tags (4)
- `get_tags` — List all tags
- `create_tag` — Create a tag
- `update_tag` — Update a tag
- `delete_tag` — Delete a tag

### Notebooks (6)
- `get_notebooks` — List all notebooks
- `get_notebooks_by_project` — Notebooks for a project
- `get_notebook_by_id` — Get a single notebook
- `create_notebook` — Create a notebook
- `update_notebook` — Update a notebook
- `delete_notebook` — Delete a notebook

### Messages (4)
- `get_messages` — List all messages
- `get_messages_by_project` — Messages for a project
- `get_message_by_id` — Get a single message
- `create_message` — Post a message

### Files (3)
- `get_files_by_project` — Files in a project
- `get_file_by_id` — Get a single file
- `delete_file` — Delete a file

### Risks (3)
- `get_risks` — List all risks
- `get_risks_by_project` — Risks for a project
- `create_risk` — Create a risk

### Links (2)
- `get_links_by_project` — Links in a project
- `create_link` — Create a link in a project

### Calendar (1)
- `get_calendar_events` — List calendar events

### Expenses (1)
- `get_expenses` — List all expenses

### Categories (1)
- `get_project_categories` — List project categories

### Webhooks (3)
- `get_webhooks` — List all webhooks
- `create_webhook` — Create a webhook
- `delete_webhook` — Delete a webhook

### Custom Fields (1)
- `get_custom_fields_by_project` — Custom fields for a project

### Job Roles (1)
- `get_job_roles` — List all job roles

### Timezones (1)
- `get_timezones` — List all supported timezones

## Roadmap

See [ROADMAP.md](ROADMAP.md) for planned improvements including: full CRUD for expenses/risks/files, timer controls, resource allocations, reporting tools, pagination helpers, retry logic, and a test suite.

## Architecture

```
src/
├── index.ts          # MCP server entry point
├── config.ts         # Environment config & auth
├── client.ts         # TeamworkClient (native fetch, v1/v3 API)
├── tool-helper.ts    # Error handling wrapper
└── tools/            # One file per domain (22 files)
    ├── account.ts
    ├── projects.ts
    ├── tasks.ts
    └── ...
```

- **Zero unnecessary dependencies** — only `@modelcontextprotocol/sdk` and `zod`
- **Native fetch** — no axios, no HTTP library bloat
- **Both v1 and v3 API** — v3 for list endpoints with pagination; v1 for mutations and resources not yet in v3
- **API token auth** (recommended) with username/password fallback

## License

MIT