Teamwork MCP Server

A Model Context Protocol (MCP) server that connects to the Teamwork API, allowing AI agents to interact with projects, time entries, people, and companies.

Functionalities (Tools)

This server exposes the following tools:

Projects & Time Tracking

• list_projects: Comprehensive project listing with 50+ filters (date, health, status, tags, etc.) and full API response support.
• create_time_entry: Creates a time entry (timelog) for a specific project.
• get_time_entries: Retrieves detailed time entries with 60+ filters (billed status, users, tags, etc.).
• total_count_of_active_projects: Returns the total count of active projects.
• total_billable_time_per_project: Returns total billable minutes per project (optional date range).
• get_health_stats: Returns project health metrics (Good, Bad, OK, etc.), with various filters.
• get_project_time_totals: Returns total hours/minutes for a project (optionally filtered by user).

Project Categories

• list_of_project_categories: Lists all project categories with filtering options.
• get_specific_project_category: Retrieves details of a specific category.
• list_of_teamwork_project_categories: Helper tool to list categories.

People & Companies

• list_people: Lists all people across the site with comprehensive filtering (user type, search term, job role, etc.).
• get_project_people: Lists all people associated with a project, with 30+ optional filters.
• get_person: Retrieves detailed information about a specific person (user).
• list_companies: Lists companies (clients).
• get_company: Retrieves details of a specific company.

Projects & Updates

• get_project: Retrieves detailed information about a specific project, with comprehensive filtering and include options.
• get_all_project_updates: Lists updates across all projects.
• get_project_updates: Lists updates for a specific project.

Tags

• get_all_tags: Lists all tags with filtering by name, item type, etc.
• get_tag: Retrieves details of a specific tag.

Configuration

To use this server, you need to configure the following environment variables:

• TEAMWORK_SITE_NAME: Your Teamwork site name/subdomain (e.g., agencyname).
• TEAMWORK_USERNAME: Your Teamwork username or email.
• TEAMWORK_PASSWORD: Your Teamwork password or API Key.

Prerequisites

Before using this MCP server, ensure you have:

• Node.js: Version 18 or higher installed. Download Node.js
• Teamwork Account: You must have an active Teamwork account.
• API Credentials: You need your Teamwork Site Name and an API Key (or password) to authenticate.

Quick Start

You can run this server directly using npx without installing it globally or cloning the repository.

Client Configuration (Claude Desktop / IDEs)

To add this server to an MCP client, simply add the following to your MCP configuration file:

{
  "mcpServers": {
    "teamwork": {
      "command": "npx",
      "args": [
        "-y",
        "@jorgeluismlima/teamwork-mcp"
      ],
      "env": {
        "TEAMWORK_SITE_NAME": "your-site-name",
        "TEAMWORK_USERNAME": "your-username",
        "TEAMWORK_PASSWORD": "your-password-or-api-key"
      }
    }
  }
}

Local Development & Installation

If you want to modify the code or run it locally from the source:

1. Clone and Install:

   git clone <repository-url>
   cd teamwork-mcp
   npm install

2. Build the project:

   npm run build

3. Run the server:

   node dist/index.js