Teamwork MCP
The Teamwork MCP server provides a simplified interface for interacting with Teamwork through RESTful API endpoints, allowing you to:
Project Management: Retrieve, create, and manage projects
Task Management: Create, update, delete tasks and subtasks; access task metrics and comments
People Management: Manage team members and their project assignments; retrieve utilization metrics
Company Management: Create, update, and delete companies
Reporting & Metrics: Generate reports on task completion, user performance, and utilization
Time Management: Access time entries and project allocations
Comments: Create comments for tasks, milestones, notebooks, and files
Integration: Easily integrate with applications like Cursor via MCP capabilities
Supports configuration management for the Teamwork MCP server, allowing secure storage of API credentials and server settings.
Serves as the runtime environment for the MCP server that connects to Teamwork, enabling project management operations like retrieving, creating, updating, and deleting tasks.
Enables seamless interaction with the Teamwork project management API, providing tools for managing projects, tasks, subtasks, people, and generating reports like utilization data in various formats.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Teamwork MCP show me all tasks for project 12345 that are overdue"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Teamwork MCP
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 TeamworkgetCurrentProject- Gets details about the current projectcreateProject- Create a new project in Teamwork
Task Tools
getTasks- Get all tasks from TeamworkgetTasksByProjectId- Get all tasks from a specific project in TeamworkgetTaskListsByProjectId- Get all task lists from a specific project in TeamworkgetTasksByTaskListId- Gets all tasks from a specific task list ID from TeamworkgetTaskById- Get a specific task by ID from TeamworkcreateTask- Create a new task in TeamworkcreateSubTask- Create a new subtask under a parent task in TeamworkupdateTask- Update an existing task in TeamworkdeleteTask- Delete a task from TeamworkgetTasksMetricsComplete- Get the total count of completed tasks in TeamworkgetTasksMetricsLate- Get the total count of late tasks in TeamworkgetTaskSubtasks- Get all subtasks for a specific task in TeamworkgetTaskComments- 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 filteringgetCompanyById- Get a specific company by IDcreateCompany- Create a new company in TeamworkupdateCompany- Update an existing company's informationdeleteCompany- Delete a company from Teamwork
People Tools
getPeople- Get all people from TeamworkgetPersonById- Get a specific person by ID from TeamworkgetProjectPeople- Get all people assigned to a specific project from TeamworkaddPeopleToProject- Add people to a specific project in TeamworkdeletePerson- Delete a person from TeamworkupdatePerson- Update a person's information (timezone, name, email, etc.)getProjectsPeopleMetricsPerformance- Get people metrics performancegetProjectsPeopleUtilization- Get people utilizationgetProjectPerson- Get a specific person on a project
Reporting Tools
getProjectsReportingUserTaskCompletion- Get user task completion reportgetProjectsReportingUtilization- Get utilization report in various formats CSV & HTML
Time Tools
getTime- Get all time entriesgetProjectsAllocationsTime- Get project allocations timegetTimezones- Get all available timezones in Teamwork (useful when updating user timezones)
Installation
Using NPX (Recommended)
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-mcpYou can also pass configuration options directly:
npx @vizioz/teamwork-mcp --domain=your-company --user=your-email@example.com --pass=your-passwordConfiguration
Setting Credentials
You can provide your Teamwork credentials in three ways:
Environment Variables: Set
TEAMWORK_DOMAIN,TEAMWORK_USERNAME, andTEAMWORK_PASSWORDin your environment..env File: Create a
.envfile with the required variables:TEAMWORK_DOMAIN=your-company TEAMWORK_USERNAME=your-email@example.com TEAMWORK_PASSWORD=your-passwordCommand 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-passwordOr 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:
Command Line Arguments:
npx @vizioz/teamwork-mcp --disable-loggingOr using the alternative form:
npx @vizioz/teamwork-mcp --no-loggingEnvironment 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 messagescombined.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:
Allow List: Only expose specific tools:
npx @vizioz/teamwork-mcp --allow-tools=getProjects,getTasks,getTaskByIdOr using short form:
npx @vizioz/teamwork-mcp --allow=getProjects,getTasks,getTaskByIdDeny List: Expose all tools except those specified:
npx @vizioz/teamwork-mcp --deny-tools=deleteTask,updateTaskOr 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:
Allow List with Groups: Only expose specific groups of tools:
npx @vizioz/teamwork-mcp --allow-tools=Tasks,PeopleOr using short form:
npx @vizioz/teamwork-mcp --allow=Tasks,PeopleDeny List with Groups: Expose all tools except those in specified groups:
npx @vizioz/teamwork-mcp --deny-tools=Reporting,TimeOr 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:
When listing available tools (tools not in the allow list or in the deny list won't be visible)
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 = YourTeamworkProjectIDThis 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
Open Cursor Settings > Features > MCP
Click "+ Add New MCP Server"
Enter a name for the server (e.g., "Teamwork API")
Select "stdio" as the transport type
Enter the command to run the server:
npx @vizioz/teamwork-mcpand add the credentials and domain command line arguments as mentioned above.You can include tool filtering options:
--allow=getProjects,getTasksor--deny=deleteTask
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
Clone the repository:
git clone https://github.com/readingdancer/teamwork-mcp.git cd teamwork-mcpInstall dependencies:
npm installCreate a
.envfile based on the.env.examplefile:cp .env.example .envUpdate the
.envfile 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 buildThis 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.jsOr 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-passwordYou can also use the short form:
node C:/your-full-path/build/index.js --domain=your-company --user=your-email@example.com --pass=your-passwordUsing the MCP Inspector
To run the MCP inspector for debugging:
npm run inspectorLicense
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 toolsaddPeopleToProjectB
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).
deleteCompanyADestructive
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).
deletePersonBDestructive
Delete a person from Teamwork
Inputs: personId (required).
deleteTaskBDestructive
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.
getProjectPersonBRead-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).
getTasksARead-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
Scored across 36 tools
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.
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.
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.
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
Related MCP Connectors
The Teamwork.com official MCP server helps teams efficiently manage client projects with AI.
A MCP server built for developers enabling Git based project management with project and personal…
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- MIT
- MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that integrates with the Tweek API to manage calendars, tasks, and custom colors. It enables users to perform full task CRUD operations, list accessible calendars, and fetch color preferences through secure authentication.1MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that connects to the Teamwork API, providing tools to manage projects, tasks, companies, people, time entries, and reports, with built-in competitive intelligence capabilities.36 npmMIT