Teamwork.com MCP server

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.

📖 Full HTTP CLI Documentation

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_CERTS environment 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