mcp

Teamwork.com MCP server

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio teamwork-mcp go run cmd/mcp-http/main.go \
  --env TW_MCP_BEARER_TOKEN="<your-bearer-token>" \
  --env TW_MCP_SERVER_ADDRESS="0.0.0.0:8080"

How to use

This MCP server provides a standardized interface for large language models to interact with Teamwork.com data. It exposes three collaboration-ready entry points: a production-ready HTTP server, a direct STDIO server for desktop and development use, and a lightweight HTTP CLI for testing and debugging MCP capabilities. Through these interfaces, LLMs can discover and invoke tools such as tasks, projects, timers, and other Teamwork domain actions supported by the server. Authentication is supported via bearer tokens and OAuth2, enabling secure access to your Teamwork.com instance. Start by deploying one of the servers (HTTP for cloud deployments, STDIO for local development, or the CLI for quick tests), then use the provided tooling to list, describe, and execute available MCP tools.

How to install

Prerequisites:

Go 1.26 or later installed on your machine
Access to a Teamwork.com account with valid API credentials (bearer token or OAuth2) for authentication

Installation steps:

Clone the repository: git clone https://github.com/teamwork/mcp.git cd mcp
Build or run the HTTP server (production path):
- To run directly (development): go run cmd/mcp-http/main.go
- To build a binary and run: go build -o mcp-http ./cmd/mcp-http ./mcp-http
Run the STDIO server (development path): go run cmd/mcp-stdio/main.go
Run the HTTP CLI tool for testing: go run cmd/mcp-http-cli/main.go -mcp-url=http://localhost:8080 list-tools

Note: If you plan to use OAuth2 with Let's Encrypt certificates in staging, ensure you set NODE_EXTRA_CA_CERTS when using any Node-based tooling, as described in the usage guide.

Environment variables you may need:

TW_MCP_SERVER_ADDRESS: address to bind the HTTP server (e.g., 0.0.0.0:8080)
TW_MCP_BEARER_TOKEN: your Teamwork.com bearer token for authentication
Any OAuth2 config required by your Teamwork.com credentials

For production deployments, consider containerizing the service (Dockerfile provided) and running with environment-driven configuration.

Additional notes

Tips and common issues:

If you encounter TLS/CA certificate issues when using OAuth2 against Let's Encrypt in staging, set NODE_EXTRA_CA_CERTS as documented in the usage guide when invoking Node-based tooling.
Ensure your Teamwork.com API credentials have the necessary scopes for the actions you plan to perform (tasks, timers, projects, etc.).
When using the STDIO server, tokens are passed via environment variables; ensure they are securely managed in your local environment.
The server supports a read-only mode to restrict operations; enable it if you want to limit write actions during exploration.
Check logs frequently during development; the architecture includes modular components for auth, request handling, and toolsets to help pinpoint issues quickly.