Skip to main content
Glama
Teamwork MCP
by Vizioz

Teamwork MCP

npm version

An MCP server that connects to the Teamwork API, providing a simplified interface for interacting with Teamwork projects and tasks.

Features

  • Connect to Teamwork API

  • Retrieve projects and tasks

  • Create, update, and delete tasks

  • RESTful API endpoints

  • Error handling and logging

  • MCP server for integration with Cursor and other applications

Related MCP server: Teamwork

Prerequisites

  • Node.js (v14.17 or higher, recommend 18+ or even better latest LTS version)

  • npm or yarn

  • Teamwork account with API access

Available Teamwork MCP Tools

The following tools are available through the MCP server:

Project Tools

  • getProjects - Get all projects from Teamwork

  • getCurrentProject - Gets details about the current project

  • createProject - Create a new project in Teamwork

Task Tools

  • getTasks - Get all tasks from Teamwork

  • getTasksByProjectId - Get all tasks from a specific project in Teamwork

  • getTaskListsByProjectId - Get all task lists from a specific project in Teamwork

  • getTasksByTaskListId - Gets all tasks from a specific task list ID from Teamwork

  • getTaskById - Get a specific task by ID from Teamwork

  • createTask - Create a new task in Teamwork

  • createSubTask - Create a new subtask under a parent task in Teamwork

  • updateTask - Update an existing task in Teamwork

  • deleteTask - Delete a task from Teamwork

  • getTasksMetricsComplete - Get the total count of completed tasks in Teamwork

  • getTasksMetricsLate - Get the total count of late tasks in Teamwork

  • getTaskSubtasks - Get all subtasks for a specific task in Teamwork

  • getTaskComments - Get comments for a specific task from Teamwork

Comment Tools

  • createComment - Create a comment related to a task/message/notebook

Company Tools

  • getCompanies - Get all companies from Teamwork with optional filtering

  • getCompanyById - Get a specific company by ID

  • createCompany - Create a new company in Teamwork

  • updateCompany - Update an existing company's information

  • deleteCompany - Delete a company from Teamwork

People Tools

  • getPeople - Get all people from Teamwork

  • getPersonById - Get a specific person by ID from Teamwork

  • getProjectPeople - Get all people assigned to a specific project from Teamwork

  • addPeopleToProject - Add people to a specific project in Teamwork

  • deletePerson - Delete a person from Teamwork

  • updatePerson - Update a person's information (timezone, name, email, etc.)

  • getProjectsPeopleMetricsPerformance - Get people metrics performance

  • getProjectsPeopleUtilization - Get people utilization

  • getProjectPerson - Get a specific person on a project

Reporting Tools

  • getProjectsReportingUserTaskCompletion - Get user task completion report

  • getProjectsReportingUtilization - Get utilization report in various formats CSV & HTML

Time Tools

  • getTime - Get all time entries

  • getProjectsAllocationsTime - Get project allocations time

  • getTimezones - Get all available timezones in Teamwork (useful when updating user timezones)

Installation

The easiest way to use Teamwork MCP is with npx. This method doesn't require cloning the repository or building the code locally:

npx @vizioz/teamwork-mcp

You can also pass configuration options directly:

npx @vizioz/teamwork-mcp --domain=your-company --user=your-email@example.com --pass=your-password

Configuration

Setting Credentials

You can provide your Teamwork credentials in three ways:

  1. Environment Variables: Set TEAMWORK_DOMAIN, TEAMWORK_USERNAME, and TEAMWORK_PASSWORD in your environment.

  2. .env File: Create a .env file with the required variables:

    TEAMWORK_DOMAIN=your-company
    TEAMWORK_USERNAME=your-email@example.com
    TEAMWORK_PASSWORD=your-password
  3. Command Line Arguments: Pass credentials when running the application:

    npx @vizioz/teamwork-mcp --teamwork-domain=your-company --teamwork-username=your-email@example.com --teamwork-password=your-password

    Or using short form:

    npx @vizioz/teamwork-mcp --domain=your-company --user=your-email@example.com --pass=your-password

Logging Configuration

By default, the Teamwork MCP server creates log files in a logs directory to help with debugging and monitoring. You can disable logging completely using the following methods:

  1. Command Line Arguments:

    npx @vizioz/teamwork-mcp --disable-logging

    Or using the alternative form:

    npx @vizioz/teamwork-mcp --no-logging
  2. Environment Variable:

    DISABLE_LOGGING=true npx @vizioz/teamwork-mcp

When logging is enabled, the server creates two log files in the logs directory:

  • error.log - Contains only error-level messages

  • combined.log - Contains all log messages (info, warnings, errors)

Each log file includes a header with instructions on how to disable logging if needed.

Tool Filtering

You can control which tools are available to the MCP server using the following command-line arguments:

  1. Allow List: Only expose specific tools:

    npx @vizioz/teamwork-mcp --allow-tools=getProjects,getTasks,getTaskById

    Or using short form:

    npx @vizioz/teamwork-mcp --allow=getProjects,getTasks,getTaskById
  2. Deny List: Expose all tools except those specified:

    npx @vizioz/teamwork-mcp --deny-tools=deleteTask,updateTask

    Or using short form:

    npx @vizioz/teamwork-mcp --deny=deleteTask,updateTask

Tool Filtering with Groups

You can now specify groups of tools for filtering, allowing for more flexible control over which tools are available to the MCP server. The available groups are:

  • Projects: Includes all project-related tools.

  • Tasks: Includes all task-related tools.

  • People: Includes all people-related tools.

  • Reporting: Includes all reporting-related tools.

  • Time: Includes all time-related tools.

  • Comments: Includes specific comment tools.

Using Groups in Tool Filtering

You can specify these groups in the allow or deny lists to include or exclude all tools within a group. For example:

  1. Allow List with Groups: Only expose specific groups of tools:

    npx @vizioz/teamwork-mcp --allow-tools=Tasks,People

    Or using short form:

    npx @vizioz/teamwork-mcp --allow=Tasks,People
  2. Deny List with Groups: Expose all tools except those in specified groups:

    npx @vizioz/teamwork-mcp --deny-tools=Reporting,Time

    Or using short form:

    npx @vizioz/teamwork-mcp --deny=Reporting,Time

By default, all tools are exposed if neither allow nor deny list is provided. If both are provided, the allow list takes precedence.

The tool filtering is enforced at two levels for enhanced security:

  1. When listing available tools (tools not in the allow list or in the deny list won't be visible)

  2. When executing tool calls (attempts to call filtered tools will be rejected with an error)

Setting Up Your Teamwork Project

To associate your current solution with a Teamwork project, you can use the following method:

Using a Configuration File

You can create a .teamwork file in the root of your project with the following structure:

PROJECT_ID = YourTeamworkProjectID

This simple configuration file associates your solution with a specific Teamwork project, we may use it to store more details in the future.

Once configured, the MCP will be able to find your Teamwork project and associate it with your current solution, reducing the number of API calls needed to get the project and tasks related to the solution you are working on.

Adding to MCP Clients

Cursor

To add this MCP server to Cursor:

Versions before 0.47

  1. Open Cursor Settings > Features > MCP

  2. Click "+ Add New MCP Server"

  3. Enter a name for the server (e.g., "Teamwork API")

  4. Select "stdio" as the transport type

  5. Enter the command to run the server: npx @vizioz/teamwork-mcp and add the credentials and domain command line arguments as mentioned above.

    • You can include tool filtering options: --allow=getProjects,getTasks or --deny=deleteTask

  6. Click "Add"

Versions after 0.47 (editing the config manually)

"Teamwork": {
  "command": "npx",
  "args": [
    "-y",
    "@vizioz/teamwork-mcp",
    "--domain",
    "yourdomain",
    "--user",
    "youruser@yourdomain.com",
    "--pass",
    "yourPassword"
  ]
}

To disable logging in Cursor, add the --disable-logging argument:

"Teamwork": {
  "command": "npx",
  "args": [
    "-y",
    "@vizioz/teamwork-mcp",
    "--domain",
    "yourdomain",
    "--user",
    "youruser@yourdomain.com",
    "--pass",
    "yourPassword",
    "--disable-logging"
  ]
}

If you want to add the allow or deny arguments mentioned above you just add them like this, you can add any of the examples given above, you can also add both groups and individual tools as shown below:

"Teamwork": {
  "command": "npx",
  "args": [
    "-y",
    "@vizioz/teamwork-mcp",
    "--domain",
    "yourdomain",
    "--user",
    "youruser@yourdomain.com",
    "--pass",
    "yourPassword",
    "--allow",
    "Tasks,Projects",
    "--deny",
    "getProjectsPeopleMetricsPerformance,getProjectsPeopleUtilization"
  ]
}

The Teamwork MCP tools will now be available to the Cursor Agent in Composer.

Claude Desktop

To add this MCP server to Claude Desktop, edit your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "teamwork": {
      "command": "npx",
      "args": [
        "-y",
        "@vizioz/teamwork-mcp",
        "--domain",
        "yourdomain",
        "--user",
        "youruser@yourdomain.com",
        "--pass",
        "yourPassword"
      ]
    }
  }
}

Windsurf

To add this MCP server to Windsurf, follow similar steps to Cursor by adding the MCP server configuration with the npx command and your credentials.

Building from Source

Note: You only need to follow these instructions if you plan to contribute to the project or submit a pull request. For regular usage, use the NPX installation method above.

Local Development Setup

  1. Clone the repository:

    git clone https://github.com/readingdancer/teamwork-mcp.git
    cd teamwork-mcp
  2. Install dependencies:

    npm install
  3. Create a .env file based on the .env.example file:

    cp .env.example .env
  4. Update the .env file with your Teamwork credentials:

    PORT=3000
    NODE_ENV=development
    LOG_LEVEL=info
    TEAMWORK_DOMAIN=your-company
    TEAMWORK_USERNAME=your-email@example.com
    TEAMWORK_PASSWORD=your-password

Building the Application

Build the application:

npm run build

This will compile the TypeScript code ready to be used as an MCP Server.

Running as an MCP Server (Local Build)

To run as an MCP server for integration with Cursor and other applications, if you are using the .env file for your username, password & url, or if you have saved them in environment variables:

NOTE: Don't forget to change the drive and path details based on where you have saved the repository.

node C:/your-full-path/build/index.js

Or you can pass them using line arguments:

node C:/your-full-path/build/index.js --teamwork-domain=your-company --teamwork-username=your-email@example.com --teamwork-password=your-password

You can also use the short form:

node C:/your-full-path/build/index.js --domain=your-company --user=your-email@example.com --pass=your-password

Using the MCP Inspector

To run the MCP inspector for debugging:

npm run inspector

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Teamwork.com. The use of the name "Teamwork" in the package name (@vizioz/teamwork-mcp) is solely for descriptive purposes to indicate compatibility with the Teamwork.com API.

Available Tools

36 tools
addPeopleToProjectB

Add people to a specific project in Teamwork

Inputs: projectId (required), userIds (required), checkTeamIds.

createCommentB

Creates a new comment for a specific resource (tasks, milestones, notebooks, links, fileversions) in Teamwork

Inputs: resource (required), resourceId (required), body (required), notify, +4 more.

createCompanyC

Create a new company. This tool allows you to create a company. The request requires a companyRequest object with various properties like addressOne, emailOne, name, and tags.

Inputs: companyRequest (required), options.

createProjectB

Create a new project in Teamwork

Inputs: name (required), description, companyId, categoryId, +3 more.

createSubTaskB

Creates a subtask. Create a new subtask under the provided parent task.

Inputs: taskRequest (required), taskId (required).

createTaskB

Creates a task. Create a new task in the provided task list.

Inputs: taskRequest (required), tasklistId (required).

deleteCompanyA
Destructive

This tool allows you to delete a company, be careful with this tool as it will delete the company and all associated data. It requires the following parameters: companyId.

Inputs: companyId (required).

deletePersonB
Destructive

Delete a person from Teamwork

Inputs: personId (required).

deleteTaskB
Destructive

Delete a task from Teamwork

Inputs: taskId (required).

getCompaniesB

Get a list of companies, retrieve all companies for the provided filters. This endpoint allows you to filter companies by various parameters including custom fields, tags, search terms, and more.

Inputs: searchTerm, page, pageSize, orderBy, +5 more.

getCompanyByIdB

Get a specific company by ID. Retrieves detailed information about a company identified by its ID.

Inputs: companyId (required), includeCustomFields, fullProfile, getStats.

getCurrentProjectA

Get the current solution's Teamwork project, always check the .teamwork file in the root of the solution for the Teamwork project ID or ask the user which project they are working on.

Inputs: projectId (required).

getPeopleC

Get all people from Teamwork

Inputs: userType, updatedAfter, searchTerm, orderMode, +9 more.

getPersonByIdB

Get a specific person by ID from Teamwork

Inputs: personId (required).

getProjectPeopleB

Get all people assigned to a specific project from Teamwork

Inputs: projectId (required), userType, searchTerm, orderMode, +4 more.

getProjectPersonB
Read-onlyIdempotent

Returns one or more people on a project. Retrieve a person(s) record.

Inputs: projectId (required), personId (required), userType, updatedAfter, +31 more.

getProjectsC

Get all projects from Teamwork

Inputs: updatedAfter, timeMode, searchTerm, reportType, +36 more.

getProjectsAllocationsTimeB

Get time entries for a specific allocation. Return logged time entries for a specific allocation. Only the time entries that the logged-in user can access will be returned.

Inputs: allocationId (required), updatedAfter, startDate, endDate, +6 more.

getProjectsPeopleMetricsPerformanceA

Performance of users completing the most tasks. Count the number of completed tasks by user for the provided period. By default the user with the most completed tasks is shown first.

Inputs: startDate, endDate, orderMode.

getProjectsPeopleUtilizationC

Return the user utilization data. This endpoint provides detailed information about user utilization, including billable and non-billable time, availability, and various utilization metrics.

Inputs: zoom, startDate, sortOrder, sort, +27 more.

getProjectsReportingUserTaskCompletionC

Returns task completions for a given user. Retrieve a person record and its task completion stats.

Inputs: userId (required), userType, updatedAfter, startDate, +37 more.

getProjectsReportingUtilizationA

Generate utilization report in various formats (CSV, HTML, PDF, XLSX). Generates a utilization report containing all people for the provided filters. Only the people that the logged-in user can access will be returned.

Inputs: format (required), zoom, startDate, sortOrder, +28 more.

getTaskByIdB

Get a specific task by ID from Teamwork

Inputs: taskId (required).

getTaskCommentsA

Get comments for a specific task from Teamwork

Inputs: taskId (required), page, pageSize, orderBy, +4 more.

getTaskListsByProjectIdB

Get all task lists by project ID

Inputs: projectId (required).

getTasksA
Read-onlyIdempotent

Get tasks, Return multiple tasks according to the optional provided filter.

Inputs: updatedBefore, updatedAfter, today, taskFilter, +132 more.

getTasksByProjectIdB

Get all tasks from a specific project in Teamwork

Inputs: projectId (required).

getTasksByTaskListIdC

Get all tasks from a specific task list in Teamwork

Inputs: tasklistId (required), page, pageSize, includeCompletedTasks.

getTasksMetricsCompleteB

Get the total count of completed tasks in Teamwork

Inputs: no named parameters.

getTasksMetricsLateC

Get the total count of late tasks in Teamwork

Inputs: no named parameters.

getTaskSubtasksB

Get all subtasks for a specific task in Teamwork

Inputs: taskId (required), page, pageSize, includeCompletedTasks.

getTimeB

Get all time entries. Return all logged time entries for all projects. Only the time entries that the logged-in user can access will be returned.

Inputs: updatedAfter, startDate, reportFormat, projectStatus, +15 more.

getTimezonesA

Get all timezones available in Teamwork. This is useful when you need to update a user's timezone and need to know the available options.

Inputs: no named parameters.

updateCompanyC

This tool allows you to update a company. It requires parameters: companyId and companyRequest.

Inputs: companyId (required), companyRequest (required), options.

updatePersonB

Update a person in Teamwork. This endpoint allows you to modify user information like timezone, name, email, etc.

Inputs: personId (required), first-name, last-name, email-address, +6 more.

updateTaskB

Update an existing task. Modify the properties of an existing task.

Inputs: taskId (required), taskRequest (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 36 tools

    Disambiguation3/5

    Tool purposes are mostly clear, but several overlap: getProjectPerson/getProjectPeople/getPersonById, getTasks/getTasksByProjectId/getTasksByTaskListId, and the reporting tools (getProjectsPeopleMetricsPerformance, getProjectsReportingUserTaskCompletion, getProjectsPeopleUtilization) have similar names and data targets. Users need to read descriptions carefully to choose the right one.

    Naming Consistency4/5

    The get/create/update/delete verb pattern is consistent across projects, tasks, people, and companies. Some names are awkward or verbose (getProjectPerson, getTasksMetricsComplete, getProjectsReportingUserTaskCompletion), but the overall convention is predictable and readable.

    Tool Count3/5

    36 tools is on the heavy sidecka, and several retrieval/reporting endpoints overlap and could be consolidated. However, the server spans multiple related domains (projects, tasks, people, companies, time, reports), so the large count is somewhat justified by the broad scope.

    Completeness3/5

    Tasks and companies have solid CRUD coverage, but there are notable gaps: no project update/delete, no task list management, no person creation, and time entries can be retrieved but not created or modified. Common workflows are covered, but agents will hit dead ends for lifecycle operations.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers