com.teamwork/mcp

The Teamwork.com official MCP server helps teams efficiently manage client projects with AI.

Open source Repository Open in the app JSON README (API)

About

The Teamwork.com official MCP server helps teams efficiently manage client projects with AI.

Details

Kind: MCP servers
Topic: No topic detected
Publisher: com.teamwork
Origin: official
Category: ferramentas
Transport: sse
Version: 1.39.0
Stars: 25
Forks: 17
Open pull requests: 2
Last push: 2026-09-08T11:56:50Z
Repository state: ativo
Language: Go
License: MIT
Added: 2026-08-29 03:01:24
Updated: 2026-09-11 15:01:03
Origin id: com.teamwork/mcp

README

# Teamwork MCP Server

> Model Context Protocol server for Teamwork.com integration with Large Language
> Models

[![Go Report Card](https://goreportcard.com/badge/github.com/teamwork/mcp)](https://goreportcard.com/report/github.com/teamwork/mcp)
[![Go](https://img.shields.io/badge/Go-1.27.0-blue.svg)](https://golang.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

📌 Are you a Teamwork.com user wanting to connect AI tools to your Teamwork.com
site right now? Jump straight to the **[Usage Guide](docs/usage/README.md)** 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](docs/tool-reference.md)** 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](https://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](cmd/mcp-http/README.md)**

Quick start:
```bash
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](cmd/mcp-stdio/README.md)**

Quick start:
```bash
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](cmd/mcp-http-cli/README.md)**

Quick start:
```bash
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
```bash
# Run all tests
go test ./...

# Run specific package tests
go test ./internal/twprojects/
```

### MCP Inspector
For debugging purposes, use the [MCP Inspector tool](https://github.com/modelcontextprotocol/inspector):

```bash
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](https://letsencrypt.org/certs/staging/letsencrypt-stg-root-x1.pem).

## 🏗️ 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
```

com.teamwork/mcp

About

Details

README

More