teamwork
# teamwork-mcp
[](https://www.npmjs.com/package/@sondv5/teamwork-mcp)
[](https://github.com/sondv5/teamwork-mcp/actions/workflows/ci.yml)
[](LICENSE)
MCP server for **Teamwork.com** — tasks, projects, people, time tracking and search
for any MCP client (Claude Code, Claude Desktop, Cursor, Codex, opencode, ...).
Your API key is verified once and stored in the **OS keychain** — never in config files.
## Install
```bash
npx -y @sondv5/teamwork-mcp@latest # run directly
claude plugin install teamwork@teamwork-mcp # Claude Code plugin (after: claude plugin marketplace add sondv5/teamwork-mcp)
```
MCP client config:
```json
{ "mcpServers": { "teamwork": { "command": "npx", "args": ["-y", "@sondv5/teamwork-mcp@latest"] } } }
```
On first use, a local setup page opens (`127.0.0.1`) — enter your site + key once, then
retry. Get a key in Teamwork: **Profile → Edit My Details → API & Mobile → Show your Token**.
CLI: `npx -y @sondv5/teamwork-mcp@latest auth | status | logout`.
## Tools
| Tool | Actions |
| --- | --- |
| `tasks` | list, get, create, update, list_comments, comment |
| `projects` | list, tasklists, updates, milestones, activity |
| `people` | whoami, list, my_work |
| `time` | log |
| `search` | global keyword search |
| `system` | status, logout |
| `request` | raw V3 escape hatch (tags, teams, files, ...) |
## Environment
| Variable | Purpose |
| --- | --- |
| `TEAMWORK_SITE`, `TEAMWORK_API_KEY` | credential override for CI (plaintext) |
| `TEAMWORK_ALLOWED_SITES` | extra accepted domains (custom Teamwork hosts) |
| `TEAMWORK_MCP_NO_BROWSER=1` | print the setup URL instead of opening the browser |
## Security
- Key stored in the OS keychain; encrypted-file fallback is obfuscation only — keychain preferred.
- Setup page is loopback-only, nonce-gated, validates `Host`/`Origin`, and refuses to
overwrite an active credential (run `logout` first).
- Only `teamwork.com` / `teamworkpm.net` sites are accepted, so a key is never sent elsewhere.
- The key inherits the user's permissions — prefer a dedicated standard user over an admin key.
## Dev
```bash
npm install
npm run check && npm run lint && npm test # typecheck + eslint + unit tests
npm run test:e2e # live end-to-end test (needs TW_TEST_KEY)
```
MIT © [sondv5](https://github.com/sondv5) — [sondv5.github.io/teamwork-mcp](https://sondv5.github.io/teamwork-mcp/)
TDQS
Scored across 18 tools
Each tool targets a distinct resource or action: auth tools, project/task listing, task CRUD, comments, time logging, activity feeds, people lookup, and search. Even similar tools like list_tasks and my_work differ by scope (all tasks vs. assigned to user), and latest_activity vs. search are clearly differentiated by feed vs. keyword. No two tools appear to serve the same purpose.
Tools predominantly follow a clear verb_noun snake_case pattern (list_projects, create_task, update_task, log_time, add_task_comment). Exceptions like whoami, auth_status, and logout are idiomatic and consistent with the overall style, showing no mixed conventions or camelCase. The naming is predictable and aids agent selection.
18 tools is slightly above the ideal 3–15 range but justified by the breadth of the Teamwork.com domain: authentication, projects, task lists, tasks, comments, time, activity, milestones, project updates, and people. Each tool addresses a distinct need, so the count feels reasonable rather than bloated.
The surface covers task creation, retrieval, update, search, and comments, plus time logging and activity feeds. However, it lacks task deletion and any project or task list creation/update/delete operations, which are notable gaps for full lifecycle management. The absence of these operations could cause dead ends in workflows requiring them.