Teamwork MCP (Vizioz)

团队合作MCP

MCP服务器，连接到Teamwork API，为与Teamwork项目和任务交互提供简化的界面。

特性

• 连接到Teamwork API
• 检索项目和任务
• 创建、更新和删除任务
• RESTful API端点
• 错误处理和日志
• MCP服务器，用于与Cursor和其他应用程序集成

先决条件

• Node.js（v14.17或更高版本，推荐18+或更好的最新LTS版本）
• npm或纱线
• 具有API访问权限的团队合作帐户

可用的团队合作MCP工具

MCP服务器提供以下工具：

项目工具

• getProjects -从Teamwork获取所有项目
• getCurrentProject -获取当前项目的详细信息
• createProject -在Teamwork中创建新项目

任务工具

• getTasks -从Teamwork获取所有任务
• getTasksByProjectId -从Teamwork中的特定项目获取所有任务
• getTaskListsByProjectId -从Teamwork中的特定项目获取所有任务列表
• getTasksByTaskListId -从Teamwork获取特定任务列表ID中的所有任务
• getTaskById -从Teamwork按ID获取特定任务
• createTask -在Teamwork中创建新任务
• createSubTask -在Teamwork中的父任务下创建新的子任务
• updateTask -更新Teamwork中的现有任务
• deleteTask -从团队合作中删除任务
• getTasksMetricsComplete -获取Teamwork中已完成任务的总数
• getTasksMetricsLate -获取Teamwork中迟到任务的总数
• getTaskSubtasks -获取Teamwork中特定任务的所有子任务
• getTaskComments -从Teamwork获取特定任务的评论

评论工具

• createComment -创建与任务/消息/笔记本相关的评论

公司工具

• getCompanies -通过可选过滤从Teamwork获取所有公司
• getCompanyById -通过ID获取特定公司
• createCompany -在团队合作中创建新公司
• updateCompany -更新现有公司的信息
• deleteCompany -从团队合作中删除公司

人员工具

• getPeople -让所有人加入Teamwork
• getPersonById -通过Teamwork的ID获取特定人员
• getProjectPeople -从Teamwork中获取分配给特定项目的所有人员
• addPeopleToProject -将人员添加到Teamwork中的特定项目
• deletePerson -从团队合作中删除人员
• updatePerson -更新个人信息（时区、姓名、电子邮件等）
• getProjectsPeopleMetricsPerformance -获取人员绩效指标
• getProjectsPeopleUtilization -提高人员利用率
• getProjectPerson -让一个特定的人参与一个项目

报告工具

• getProjectsReportingUserTaskCompletion -获取用户任务完成报告
• getProjectsReportingUtilization -获取CSV和HTML等多种格式的利用率报告

时间工具

• getTime -获取所有时间条目
• getProjectsAllocationsTime -获取项目分配时间
• getTimezones -获取Teamwork中的所有可用时区（在更新用户时区时很有用）

安装

使用NPX（推荐）

使用Teamwork MCP最简单的方法是使用npx。此方法不需要克隆存储库或在本地构建代码：

npx @vizioz/teamwork-mcp

您还可以直接传递配置选项：

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

配置

设置凭据

您可以通过三种方式提供您的团队合作凭据：

1. 环境变量：设置 TEAMWORK_DOMAIN, TEAMWORK_USERNAME，以及 TEAMWORK_PASSWORD 在您的环境中。

1. .env文件：创建一个 .env 包含所需变量的文件：

   TEAMWORK_DOMAIN=your-company
   TEAMWORK_USERNAME=your-email@example.com
   TEAMWORK_PASSWORD=your-password

1. 命令行参数：运行应用程序时传递凭据：

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

或者使用缩写形式：

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

日志记录配置

默认情况下，Teamwork MCP服务器在 logs 目录，以帮助调试和监控。您可以使用以下方法完全禁用日志记录：

1. 命令行参数:

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

或者使用替代形式：

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

1. 环境变量:

   DISABLE_LOGGING=true npx @vizioz/teamwork-mcp

启用日志记录后，服务器在 logs 目录：

• error.log -仅包含错误级别消息
• combined.log -包含所有日志消息（信息、警告、错误）

每个日志文件都包含一个标头，其中包含如何在需要时禁用日志记录的说明。

工具筛选

您可以使用以下命令行参数控制MCP服务器可用的工具：

1. 允许列表：仅公开特定工具：

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

或者使用缩写形式：

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

1. 拒绝列表：露出除指定工具外的所有工具：

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

或者使用缩写形式：

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

使用组进行工具筛选

现在，您可以指定用于筛选的工具组，从而可以更灵活地控制MCP服务器可用的工具。可用的组包括：

• 项目：包括所有与项目相关的工具。
• 任务：包括所有与任务相关的工具。
• 人们：包括所有与人员相关的工具。
• 报告：包括所有与报告有关的工具。
• 时间：包括所有与时间相关的工具。
• 评论：包括特定的评论工具。

在工具筛选中使用组

您可以在允许或拒绝列表中指定这些组，以包含或排除组内的所有工具。例如：

1. 允许组列表：仅公开特定的工具组：

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

或者使用缩写形式：

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

1. 拒绝包含组的列表：显示除指定组之外的所有工具：

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

或者使用缩写形式：

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

默认情况下，如果不提供允许或拒绝列表，则所有工具都会公开。如果两者都提供，则允许列表优先。

为了增强安全性，工具过滤在两个级别上强制执行：

1. 列出可用工具时（不在允许列表或拒绝列表中的工具将不可见）
2. 执行工具调用时（调用筛选工具的尝试将被拒绝，并显示错误）

设置您的团队合作项目

要将当前解决方案与团队合作项目相关联，可以使用以下方法：

使用配置文件

您可以创建 .teamwork 项目根目录中的文件，其结构如下：

PROJECT_ID = YourTeamworkProjectID

这个简单的配置文件将您的解决方案与特定的Teamwork项目相关联，我们将来可能会使用它来存储更多详细信息。

配置后，MCP将能够找到您的团队合作项目，并将其与您当前的解决方案相关联，从而减少获取与您正在处理的解决方案相关的项目和任务所需的API调用次数。

添加到MCP客户端

光标

要将此MCP服务器添加到游标，请执行以下操作：

0.47之前的版本

1. 打开光标设置>功能>MCP
2. 点击“+添加新MCP服务器”
3. 输入服务器名称（例如“Teamwork API”）
4. 选择“stdio”作为传输类型
5. 输入运行服务器的命令： npx @vizioz/teamwork-mcp 并如上所述添加凭据和域命令行参数。

- 您可以包括工具筛选选项： --allow=getProjects,getTasks 或 --deny=deleteTask

1. 点击“添加”

0.47之后的版本（手动编辑配置）

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

要禁用Cursor中的日志记录，请添加 --disable-logging 论点：

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

如果你想添加上面提到的允许或拒绝参数，你只需像这样添加它们，你可以添加上面给出的任何示例，你也可以添加组和单个工具，如下所示：

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

Teamwork MCP工具现在可供Composer中的游标代理使用。

克劳德桌面

要将此MCP服务器添加到Claude Desktop，请编辑您的Claude Desktop配置文件：

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

添加以下配置：

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

帆板运动

要将此MCP服务器添加到Windsurf，请按照与Cursor类似的步骤，使用npx命令和凭据添加MCP服务器配置。

从源头构建

*注意：只有当您计划为项目做出贡献或提交拉取请求时，才需要遵循这些说明。对于常规使用，请使用上述NPX安装方法。*

地方发展设置

1. 克隆存储库：

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

1. 安装依赖项：

   npm install

1. 创建一个 .env 文件基于 .env.example 文件：

   cp .env.example .env

1. 更新 .env 将您的团队协作凭据归档：

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

构建应用程序

构建应用程序：

npm run build

这将编译TypeScript代码，准备用作MCP服务器。

作为MCP服务器运行（本地构建）

要作为MCP服务器运行以与Cursor和其他应用程序集成，如果您使用.env文件作为用户名、密码和url，或者您已将它们保存在环境变量中：

*注意：不要忘记根据您保存存储库的位置更改驱动器和路径详细信息。*

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

或者，您可以使用行参数传递它们：

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

您也可以使用缩写形式：

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

使用MCP检查器

要运行MCP检查器进行调试：

npm run inspector

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

免责声明

本项目不隶属于Teamwork.com、不由Teamwork.com背书或赞助。在包名称（@vizioz/Teamwork-mcp）中使用“Teamwork”名称仅用于说明目的，以表明与Teamwork.com API的兼容性。