Teamwork MCP

Teamwork MCP

一个连接 Teamwork API 的 MCP 服务，提供简化的接口，用于与 Teamwork 项目和任务交互。

功能

• 连接 Teamwork API
• 获取项目和任务
• 创建、更新和删除任务
• RESTful API 端点
• 错误处理和日志记录
• 用于与 Cursor 和其他应用程序集成的 MCP 服务

前提条件

• Node.js（v14.17 或更高版本，建议使用 18+，或更好的最新 LTS 版本）
• npm 或 yarn
• 拥有 API 访问权限的 Teamwork 账户

可用的 Teamwork MCP 工具

可通过 MCP 服务使用以下工具：

项目工具

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

任务工具

• getTasks - 获取 Teamwork 中的所有任务
• getTasksByProjectId - 获取 Teamwork 中指定项目的所有任务
• getTaskListsByProjectId - 获取 Teamwork 中指定项目的所有任务列表
• getTasksByTaskListId - 获取 Teamwork 中指定任务列表 ID 下的所有任务
• getTaskById - 根据 ID 从 Teamwork 获取指定任务
• createTask - 在 Teamwork 中创建新任务
• createSubTask - 在 Teamwork 中为父任务创建新子任务
• updateTask - 更新 Teamwork 中的现有任务
• deleteTask - 删除 Teamwork 中的任务
• getTasksMetricsComplete - 获取 Teamwork 中已完成任务的总数
• getTasksMetricsLate - 获取 Teamwork 中逾期任务的总数
• getTaskSubtasks - 获取 Teamwork 中指定任务的所有子任务
• getTaskComments - 获取 Teamwork 中指定任务的评论

评论工具

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

公司工具

• getCompanies - 获取 Teamwork 中的所有公司，可选筛选
• getCompanyById - 根据 ID 获取指定公司
• createCompany - 在 Teamwork 中创建新公司
• updateCompany - 更新现有公司的信息
• deleteCompany - 删除 Teamwork 中的公司

人员工具

• getPeople - 获取 Teamwork 中的所有人员
• getPersonById - 根据 ID 从 Teamwork 获取指定人员
• getProjectPeople - 获取 Teamwork 中分配到指定项目的所有人员
• addPeopleToProject - 将人员添加到 Teamwork 中的指定项目
• deletePerson - 删除 Teamwork 中的人员
• 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 [email protected] --pass=your-password

配置

设置凭据

你可以通过三种方式提供 Teamwork 凭据：

1. 环境变量：在环境中设置 TEAMWORK_DOMAIN、TEAMWORK_USERNAME 和 TEAMWORK_PASSWORD。

2. .env 文件：创建包含所需变量的 .env 文件：

   TEAMWORK_DOMAIN=your-company
   [email protected]
   TEAMWORK_PASSWORD=your-password
   

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

   npx @vizioz/teamwork-mcp --teamwork-domain=your-company [email protected] --teamwork-password=your-password
   

   或使用简写形式：

   npx @vizioz/teamwork-mcp --domain=your-company [email protected] --pass=your-password
   

日志配置

默认情况下，Teamwork MCP 服务会在 logs 目录中创建日志文件，以便调试和监控。你可以通过以下方法完全禁用日志记录：

1. 命令行参数：

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

   或使用替代形式：

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

2. 环境变量：

   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
   

2. 拒绝列表：公开除指定工具之外的所有工具：

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

   或使用简写形式：

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

使用分组筛选工具

现在，你可以指定工具组进行筛选，从而更灵活地控制 MCP 服务可用的工具。可用的分组如下：

• Projects：包含所有与项目相关的工具。
• Tasks：包含所有与任务相关的工具。
• People：包含所有与人员相关的工具。
• Reporting：包含所有与报告相关的工具。
• Time：包含所有与时间相关的工具。
• Comments：包含特定的评论工具。

在工具筛选中使用分组

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

1. 使用分组的允许列表：仅公开指定分组中的工具：

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

   或使用简写形式：

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

2. 使用分组的拒绝列表：公开除指定分组中的工具之外的所有工具：

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

   或使用简写形式：

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

默认情况下，如果未提供允许列表或拒绝列表，则会公开所有工具。如果同时提供两者，则以允许列表为准。

为增强安全性，工具筛选会在两个层面强制执行：

1. 列出可用工具时（不在允许列表中或位于拒绝列表中的工具不会显示）
2. 执行工具调用时（尝试调用经过筛选的工具会被拒绝并返回错误）

设置 Teamwork 项目

若要将当前解决方案关联到 Teamwork 项目，可以使用以下方法：

使用配置文件

你可以在项目根目录中创建一个 .teamwork 文件，内容结构如下：

PROJECT_ID = YourTeamworkProjectID

这个简单的配置文件会将你的解决方案关联到特定的 Teamwork 项目；我们可能会在未来用它存储更多详细信息。

配置完成后，MCP 就能找到你的 Teamwork 项目，并将其关联到当前解决方案，从而减少获取项目以及与你正在处理的解决方案相关任务所需的 API 调用次数。

添加到 MCP 客户端

Cursor

将此 MCP 服务添加到 Cursor：

0.47 之前的版本

1. 打开 Cursor Settings > Features > MCP
2. 点击“+ Add New MCP Server”
3. 输入服务名称（例如，“Teamwork API”）
4. 选择“stdio”作为传输类型
5. 输入运行服务的命令：npx @vizioz/teamwork-mcp，并添加上文提到的凭据和域名命令行参数。
   • 你可以添加工具筛选选项：--allow=getProjects,getTasks 或 --deny=deleteTask
6. 点击“Add”

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

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

要在 Cursor 中禁用日志记录，请添加 --disable-logging 参数：

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

如果你想添加上文提到的允许或拒绝参数，只需按以下方式添加即可。你可以添加上文中的任一示例，也可以像下面这样同时添加分组和单个工具：

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

现在，Cursor Composer 中的 Agent 就可以使用 Teamwork MCP 工具了。

Claude Desktop

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

Windows：%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",
        "[email protected]",
        "--pass",
        "yourPassword"
      ]
    }
  }
}

Windsurf

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

从源代码构建

注意：只有在计划为项目做贡献或提交拉取请求时，才需要按照这些说明操作。常规使用请使用上文所述的 NPX 安装方法。

本地开发环境设置

1. 克隆仓库：

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

2. 安装依赖：

   npm install
   

3. 根据 .env.example 文件创建 .env 文件：

   cp .env.example .env
   

4. 使用你的 Teamwork 凭据更新 .env 文件：

   PORT=3000
   NODE_ENV=development
   LOG_LEVEL=info
   TEAMWORK_DOMAIN=your-company
   [email protected]
   TEAMWORK_PASSWORD=your-password
   

构建应用程序

构建应用程序：

npm run build

此操作将编译 TypeScript 代码，使其可用作 MCP 服务。

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

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

注意：请务必根据仓库的保存位置更改驱动器和路径信息。

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

或者，你也可以通过行参数传递它们：

node C:/your-full-path/build/index.js --teamwork-domain=your-company [email protected] --teamwork-password=your-password

你也可以使用简写形式：

node C:/your-full-path/build/index.js --domain=your-company [email protected] --pass=your-password

使用 MCP Inspector

运行 MCP inspector 以进行调试：

npm run inspector

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

免责声明

本项目与 Teamwork.com 无关，也未获得其认可或赞助。软件包名称（@vizioz/teamwork-mcp）中使用“Teamwork”一词仅用于描述，以表明本项目与 Teamwork.com API 兼容。