MCP Server

Use This MCP server To

Check status and details of Teamwork.com projects Create and update tasks in Teamwork.com via AI Read and respond to Teamwork Desk tickets Manage Teamwork Spaces pages and content Send and read messages in Teamwork Chat Monitor project progress and deadlines Get summaries of Teamwork.com activities

README

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.

🚀 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.26 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 docs/tool-reference.md
├── 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

mcp FAQ

Can I use this to manage my Teamwork.com projects with AI?

Yes — this server lets AI tools read and update your Teamwork.com projects, tasks, and chats securely.

Does this MCP server work with popular AI models like OpenAI, Claude, or Gemini?

Yes — it supports integration with various AI models that use the MCP standard, including OpenAI, Claude, and Gemini.

Do I need a Teamwork.com account or API token to use this?

Yes — you must have valid Teamwork.com credentials (bearer token or OAuth2) to connect the server to your account.

How hard is it to set up this MCP server?

Setup is moderate — you typically copy-paste a small configuration snippet and provide your Teamwork.com token.

Which apps or clients can I use this MCP server with?

It works with any MCP-compatible AI client that supports server connections, but specific clients are not listed.

Can I restrict the AI to only view data without making changes?

Yes — the server supports a read-only mode for safer interactions.