Teamwork MCP

🚀 Teamwork MCP Project Documentation

Teamwork MCP is a tool designed for integration with the Teamwork.com platform, aiming to provide support for MCP clients such as Cursor. Written in TypeScript, this project offers a rich set of API methods to interact with and manage Teamwork projects, tasks, and other resources.

🚀 Quick Start

Teamwork MCP simplifies interaction with the Teamwork.com platform, offering seamless integration for MCP clients. Dive into the installation and configuration steps below to get started.

✨ Features

• Rich API: Offers a wide range of API methods for interacting with Teamwork projects, tasks, and other resources.
• TypeScript Based: Developed in TypeScript, ensuring type safety and maintainability.
• Multiple Installation Options: Supports installation via NPX and traditional build methods.
• Configuration Flexibility: Allows configuration through command-line arguments, environment variables, and configuration files.

📦 Installation

Using NPX (Recommended)

The simplest way to use Teamwork MCP is by running it via NPX:

npx teamwork-mcp

You can also run it by passing configuration options:

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

Building the Application

Note: If you just want to use MCP, you can directly use the NPX command without building.

Build the application:

npm run build

This will compile the TypeScript code to run as an MCP server.

Running the MCP Server

If you want to run the project as an MCP server (for integration with other applications):

Assuming you have saved your username, password, and URL in a .env file or set them as environment variables:

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

Alternatively, you can pass them via command-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 shorthand form:

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

Using the MCP Inspector (for Debugging)

To run the MCP inspector for debugging:

npm run inspector

📚 Documentation

Configuring a Teamwork Project

To associate your solution with a Teamwork project, create a .teamwork file in the project root directory with the following structure:

PROJECT_ID = YourTeamworkProjectID

This configuration file is used to identify the Teamwork project corresponding to your solution. More detailed information may be added in the future. After configuration, MCP will be able to automatically recognize your project and reduce the number of API calls required to fetch projects and related tasks.

Usage Instructions

Adding to Cursor (and other MCP clients)

If you are using an earlier version of Cursor (below 0.47):

1. Open Cursor Settings > Features > MCP.
2. Click “+ Add New MCP Server”.
3. Enter the server name (e.g., “Teamwork API”).
4. Select the transport type as “stdio”.
5. Enter the command to run the server in the command line: npx @vizioz/teamwork-mcp, and add the required credentials and domain command-line parameters.
   • You can filter tools using options such as --allow=getProjects,getTasks or --deny=deleteTask.
6. Click “Add”.

If you are using Cursor version 0.47 or above (manual configuration file editing):

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

If you want to add tool filtering options, you can do so as follows:

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

📄 License

This project is licensed under the MIT License.

⚠️ Disclaimer

This project is for example purposes only. Please read the relevant documentation and terms carefully before use.