团队协作-MCP

Name: 团队协作-MCP
Author: Vizioz

作者：Vizioz12 星标更新：2025-09-13

安装使用来源：spider==github.com

项目介绍

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 - 获取特定项目中的所有任务
getTaskListsByProjectId - 获取特定项目中的所有任务列表
getTasksByTaskListId - 根据特定任务列表ID获取所有任务
getTaskById - 根据ID获取特定任务
createTask - 在Teamwork中创建新任务
createSubTask - 在父任务下创建新子任务
updateTask - 更新Teamwork中的现有任务
deleteTask - 从Teamwork中删除任务
getTasksMetricsComplete - 获取已完成任务的总数
getTasksMetricsLate - 获取逾期任务的总数
getTaskSubtasks - 获取特定任务的所有子任务
getTaskComments - 获取特定任务的评论

评论工具

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

公司工具

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

人员工具

getPeople - 获取所有Teamwork人员
getPersonById - 根据ID从Teamwork获取特定人员
getProjectPeople - 获取分配给特定项目的所有人员
addPeopleToProject - 将人员添加到特定项目
deletePerson - 从Teamwork中删除人员
updatePerson - 更新人员的信息（时区、姓名、电子邮件等）
getProjectsPeopleMetricsPerformance - 获取人员绩效指标
getProjectsPeopleUtilization - 获取人员利用率
getProjectPerson - 获取项目上的特定人员

报告工具

getProjectsReportingUserTaskCompletion - 获取用户任务完成报告
getProjectsReportingUtilization - 获取利用率报告，格式包括CSV和HTML

时间工具

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

安装

使用NPX（推荐）

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

npx @vizioz/teamwork-mcp

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

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

配置

设置凭据

您可以使用以下三种方式提供您的Teamwork凭据：

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

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

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

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

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 目录中创建日志文件，以帮助调试和监控。您可以使用以下方法完全禁用日志记录：

命令行参数：

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

或使用替代形式：

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

环境变量：

DISABLE_LOGGING=true npx @vizioz/teamwork-mcp

当启用日志记录时，服务器会在 logs 目录中创建两个日志文件：

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

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

工具过滤

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

允许列表：仅暴露特定工具：

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

或使用短形式：

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

拒绝列表：暴露所有工具，但排除指定的工具：

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

或使用短形式：

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

使用组进行工具过滤

现在可以指定工具组进行过滤，从而更灵活地控制MCP服务器可用的工具。可用的组包括：

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

在工具过滤中使用组

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

允许列表中的组：仅暴露特定组的工具：

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

或使用短形式：

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

拒绝列表中的组：暴露所有工具，但排除指定组的工具：

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

或使用短形式：

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

如果未提供允许或拒绝列表，默认情况下将暴露所有工具。如果同时提供了允许和拒绝列表，则允许列表优先。

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

列出可用工具时（不在允许列表中或在拒绝列表中的工具不可见）
执行工具调用时（尝试调用已过滤的工具将被拒绝并返回错误）

设置您的Teamwork项目

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

使用配置文件

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

PROJECT_ID = YourTeamworkProjectID

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

配置后，MCP将能够找到您的Teamwork项目，并将其与您正在工作的解决方案关联起来，减少获取项目和相关任务所需的API调用次数。

添加到MCP客户端

Cursor

要将此MCP服务器添加到Cursor：

版本0.47之前的版本

打开Cursor设置 > 功能 > MCP
点击 "+ 添加新的MCP服务器"
输入服务器名称（例如："Teamwork API"）
选择 "stdio" 作为传输类型
输入运行服务器的命令：npx @vizioz/teamwork-mcp，并添加上述提到的凭据和域名命令行参数。
- 您可以包括工具过滤选项：--allow=getProjects,getTasks 或 --deny=deleteTask
点击 "添加"

版本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中对Cursor代理可用。

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",
        "youruser@yourdomain.com",
        "--pass",
        "yourPassword"
      ]
    }
  }
}

Windsurf

要将此MCP服务器添加到Windsurf，请按照类似于Cursor的步骤操作，通过添加带有npx命令和您的凭据的MCP服务器配置。

从源代码构建

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

本地开发设置

克隆仓库：

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

安装依赖项：
```
npm install
```
基于 .env.example 文件创建一个 .env 文件：
```
cp .env.example .env
```

更新 .env 文件，填写您的Teamwork凭据：

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许可证 - 详情请参阅 LICENSE 文件。

免责声明

本项目与Teamwork.com无任何关联、背书或赞助关系。包名中使用 "Teamwork"（@vizioz/teamwork-mcp）仅用于描述目的，以表明与Teamwork.com API的兼容性。