Teamwork MCP Server
Model Context Protocol server for Teamwork.com integration with Large Language Models
📌 Are you a Teamwork.com user wanting to connect AI tools to your Teamwork.com site right now? Jump straight to the Usage Guide for tokens, enabling MCP, and client configuration examples.
📖 Overview
This MCP (Model Context Protocol) server enables seamless integration between Large Language Models and Teamwork.com. It provides a standardized interface for LLMs to interact with Teamwork.com projects, allowing AI agents to perform various project management operations.
🤖 What is MCP?
Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. This server describes all the actions available in Teamwork.com (tools) in a way that LLMs can understand and execute through AI agents.
✨ Features
- Multiple Transport Modes: HTTP and STDIO interfaces for different deployment scenarios
- Secure Authentication: Bearer token and OAuth2 integration with Teamwork.com
- Tool Framework: Extensible toolset architecture for adding new capabilities
- Production Ready: Comprehensive logging, monitoring, and observability
- Read-Only Mode: Optional restriction to read-only operations for safety
See the auto-generated Tool Reference for every create/read/update operation exposed across Projects, Desk, Spaces, and Chat, or browse the same catalogue with per-tool descriptions and a search filter at teamwork.github.io/mcp.
🚀 Available Servers
This project provides three different ways to interact with the Teamwork.com MCP server:
📡 HTTP Server
Production-ready HTTP server for cloud deployments and multi-client support.
📖 Full HTTP Server Documentation
Quick start:
TW_MCP_SERVER_ADDRESS=:8080 go run cmd/mcp-http/main.go💬 STDIO Server
Direct STDIO interface for desktop applications and development environments.
📖 Full STDIO Server Documentation
Quick start:
TW_MCP_BEARER_TOKEN=your-token go run cmd/mcp-stdio/main.go🛠️ HTTP CLI
Command-line tool for testing and debugging MCP server functionality.
Quick start:
go run cmd/mcp-http-cli/main.go -mcp-url=https://mcp.example.com list-tools📋 Prerequisites
- Go 1.27 or later
- Valid Teamwork.com API credentials (bearer token or OAuth2 setup)
🧪 Development & Testing
Running Tests
# Run all tests
go test ./...
# Run specific package tests
go test ./internal/twprojects/MCP Inspector
For debugging purposes, use the MCP Inspector tool:
NODE_EXTRA_CA_CERTS=letsencrypt-stg-root-x1.pem npx @modelcontextprotocol/inspector node build/index.js[!IMPORTANT] Note: The
NODE_EXTRA_CA_CERTSenvironment variable is required when using OAuth2 authentication with the Let's Encrypt certification authority. Download the certificate here.
🏗️ Architecture
├── cmd/
│ ├── mcp-http/ # HTTP server implementation
│ ├── mcp-stdio/ # STDIO server implementation
│ ├── mcp-http-cli/ # CLI tool for testing via HTTP
│ ├── mcp-test/ # Walks tool handlers against a real site
│ ├── mcp-tokens/ # Token-cost report for the tool surface
│ └── docs-gen/ # Generates the tool reference (Markdown + GitHub Pages)
├── pkg/ # Importable by other MCP servers built on this one
│ ├── auth/ # Authentication helpers (bearer & OAuth2 token handling)
│ ├── cli/ # -toolsets flag parsing
│ ├── config/ # Configuration management (env, flags), MCP server setup
│ ├── helpers/ # Shared utility functions (errors, link helpers, tool parsing)
│ ├── request/ # HTTP request primitives / Teamwork API wiring
│ ├── testutil/ # Product-neutral test mocks
│ ├── toolsets/ # Tool framework and registration logic
│ └── twctx/ # Per-request values derived from the bearer token
├── internal/ # This server's own tools, not importable elsewhere
│ ├── twprojects/ # Teamwork project/domain tools (tasks, tags, timers, etc.)
│ ├── twdesk/ # Teamwork Desk tools (tickets, customers, etc.)
│ ├── twspaces/ # Teamwork Spaces tools (spaces, pages, etc.)
│ └── twchat/ # Teamwork Chat tools (conversations, messages)
├── examples/ # Usage & integration examples (LangChain Node/Python)
├── docs/usage/ # End-user setup & connection guide
├── Makefile # Common developer tasks
├── Dockerfile # Container build configuration
├── CODE_OF_CONDUCT.md # Community guidelines
├── CONTRIBUTING.md # Contribution guide
└── SECURITY.md # Security policy