Teambition-MCP
A. 模型上下文协议（MCP） Teambition的服务器项目。此项目旨在通过MCP协议实现Teambition功能的完整集成，使您能够在Claude Code、Cursor以及其他MCP兼容的客户端中直接管理Teambition的任务和项目。
🎯 项目愿景
通过MCP协议，实现Teambition平台的所有核心功能，使用户无需离开编辑器即可完成以下操作：
- ✅ 任务管理（查询、创建、更新、删除）
- 📁 项目管理
- 👥 团队协作
- 📊 数据统计与分析
- 🔔 通知管理
当前状态： 已实现任务查询功能。其他功能正在开发中。
快速导航
______________________________________________________________________
特点/功能
已实现的功能
- 📋（清单/待办事项列表） 任务查询 - 获取用户的任务列表
- 📝（笔记或记录的符号，无直接对应文字，可理解为“笔记”或“记录”） 任务详情 - 显示完整的任务信息（标题、内容、截止日期、完成状态等）
- 🔐 自动认证 - 自动处理Teambition API认证
- 📊（图表/数据表格） 格式化输出 - 将任务数据格式化为可读文本
计划中的功能
- ➕ 创建新任务
- ✏️ 更新任务信息
- 🗑️ 删除任务
- 📁 项目管理功能
- 👥 会员管理
- 🏷️ 标签管理
- 📅 日历集成
- 📈 数据统计
______________________________________________________________________
项目结构
teambition-mcp/
├── src/
│ ├── index.ts # Teambition MCP server main file
│ └── types.ts # TypeScript type definitions
├── build/ # Build output directory
├── tsconfig.json # TypeScript configuration
├── package.json # Project dependencies and scripts
├── README.md # English documentation
├── README.zh-CN.md # Chinese documentation
└── .gitignore # Git ignore configuration______________________________________________________________________
快速入门
先决条件
- Node.js 18.0或更高版本
- 纱线 或者 npm（Node Package Manager，节点包管理器）
- 带有应用凭据的Teambition账户
- 克劳德代码编辑器或光标编辑器
安装步骤
# 1. Clone the project to your local machine
git clone
cd teambition-mcp
# 2. Install project dependencies
yarn install
# 3. Build TypeScript
yarn build______________________________________________________________________
配置
步骤1：获取Teambition应用程序凭证
- 登录您的账户，然后导航至组织管理
- 创建一个新的应用程序
- 授予应用程序以下权限：
- ✓ 阅读任务 - ✓ 阅读项目信息 - ✓ 其他所需权限（基于您计划使用的功能）
- 复制并保存以下凭据：
- 应用ID - 应用程序ID - 应用密钥 - 应用密钥 - 操作员ID - 操作员ID - 组织ID - 组织ID
步骤2：配置MCP
在您的Claude代码或Cursor MCP配置文件中添加以下配置：
配置文件位置：
- 克劳德密码：
~/.config/claude-code/mcp.json - 光标：
~/.cursor/mcp.json
配置示例：
{
"mcpServers": {
"teambition-mcp": {
"command": "node",
"args": [
"/path/to/teambition-mcp/build/index.js",
"YOUR_APP_ID",
"YOUR_APP_SECRET",
"YOUR_OPERATOR_ID",
"YOUR_ORGANIZATION_ID"
]
}
}
}💡 小贴士： 将上述路径和凭据替换为实际值。建议使用绝对路径以避免路径解析问题。
步骤3：启用服务器
配置完成后，请重启您的编辑器或重新加载MCP服务器配置以开始使用。
______________________________________________________________________
使用示例
任务查询
配置完成后，您自然可以在Claude Code中就任务提出问题：
User: Query my tasks
Claude: [Display formatted task list]
User: What are my incomplete tasks?
Claude: [Filter and display incomplete tasks]
User: Show me tasks due today
Claude: [Display tasks due today]
User: List my recently created tasks
Claude: [Display tasks sorted by creation time]预期回报格式：
Status: ○ Incomplete
Title: Complete work plan
Content: Need to complete quarterly summary report by this Friday
Due Date: 2025-10-25T18:00:00.000Z
---
Status: ✓ Completed
Title: Write documentation
Content: No notes
Due Date: No due date
---______________________________________________________________________
可用工具
获取用户任务
功能： 获取当前用户的Teambition任务列表
参数： 无需参数
返回数据结构：
{
content: [
{
type: 'text',
text: string // Formatted task list text
}
]
}退货内容包括：
- 📌 任务标题
- 📄 任务内容/备注
- ✅ 完成状态（✓ 已完成 / ○ 未完成）
- 📅 截止日期
- 🕐 创建和更新时间
- 🏷️ 项目编号
使用示例：
Please query my task list
Show me all my to-do items
What tasks need my attention?API详情：
- 终端（或端点）：
GET /api/v3/usertasks/search - 认证： 承载令牌（自动处理）
- 分页： 默认返回前20个任务
______________________________________________________________________
开发指南
本地开发
# Build the project
yarn build
# Type checking only (no file generation)
yarn tsc --noEmit
# Run tests (if configured)
yarn test
# Format code
yarn prettier
# Development mode (if watch mode is configured)
yarn dev项目脚本
| 脚本 | 功能 |
|---|---|
yarn build 编译TypeScript并设置执行权限 | |
yarn test | 运行测试套件 |
yarn prettier | 源代码格式 |
代码结构解释
src/index.ts
Teambition MCP服务器的主入口文件，包含：
- 服务器初始化逻辑
- API请求包装器
- 任务查询和格式化功能
- 身份验证处理
src/types.ts
TypeScript 类型定义文件，包含：
Task- 任务数据结构UserTasksResponse- 任务列表API响应AppTokenResponse- 认证令牌响应
添加新功能
如果您想为项目添加新功能，请按照以下步骤操作：
- 定义类型 - 在（相应位置）添加必要的接口定义
types.ts - 实现功能 - 编写特征函数
index.ts - 注册工具 - 使用（某工具或方法）注册新的MCP工具
server.tool() - 测试 - 确保功能正常运行
- 更新文档 - 在README中添加新功能文档
贡献指南
我们欢迎各种形式的贡献！
- 为这个仓库创建分支
- 创建一个特性分支（
git checkout -b feature/AmazingFeature) - 提交您的更改（
git commit -m 'Add some AmazingFeature'） - 推送到分支（
git push origin feature/AmazingFeature） - 提交一个拉取请求
贡献建议：
- 实现路线图功能
- 改进错误处理
- 添加单元测试
- 优化性能
- 加强文档编写
______________________________________________________________________
路线图
v1.0（当前版本）
- \[x\] 基本项目架构
- \[x\] Teambition API 认证
- \[x\] 获取用户任务列表
- \[x\] 任务数据格式化
v1.1（计划中）
- \[ \] 创建新任务
- \[ \] 更新任务状态
- \[ \] 更新任务详情（标题、内容、截止日期等）
- \[ \] 删除任务
v1.2（计划中）
- \[ \] 项目列表查询
- \[ \] 项目详情查询
- \[ \] 任务过滤功能（按项目、状态、时间等）
v2.0（未来规划）
- \[ \] 会员管理
- \[ \] 标签管理
- \[ \] 日历集成
- \[ \] 文件管理
- \[ \] 评论功能
- \[ \] 数据统计和报告
______________________________________________________________________
常见问题解答（FAQ）
问：我如何获取Teambition应用程序的凭证？
A: 访问 Teambition开放平台登录后，在应用程序管理中创建一个新的应用程序以获取所需的凭据。
问：配置后如果无法连接到Teambition，我该怎么办？
A: 请检查以下内容：
- 验证您的凭据是否正确（应用ID、应用密钥、操作员ID、组织ID）
- 检查您的网络连接是否正常
- 确认应用程序已获得必要的权限
- 检查控制台错误日志以获取更多信息
- 验证 Node.js 版本是否满足要求（18+）
问：我可以同时使用多个Teambition账户吗？
A: 是的。你可以在配置文件中添加多个服务器实例，每个实例使用不同的凭据和名称：
{
"mcpServers": {
"teambition-work": { ... },
"teambition-personal": { ... }
}
}问：为什么我只能看到20个任务？
A: 当前版本使用默认的分页设置（每页20个项目）。未来版本将支持自定义分页参数以及检索所有任务。
问：我如何将项目更新到最新版本？
A: 在项目目录中运行：
git pull
yarn install
yarn build问：该项目支持哪些功能？
A: 目前版本仅支持任务查询功能。我们正在积极开发更多功能。请查看（相关说明/更新日志） 路线图 用于发展计划。
问：我该如何报告问题或请求新功能？
A: 请在GitHub上提交一个Issue，详细描述您遇到的问题或您想要的功能。
______________________________________________________________________
技术栈
| 技术 | 版本 | 描述 |
|---|---|---|
| TypeScript | 5.8+ | 编程语言 |
| Node.js | 18+ | 运行时环境 |
| MCP SDK | ^1.8.0 | 模型上下文协议官方SDK |
| 获取API | - | HTTP请求库（Node.js内置） |
| Zod | ^3.24.2 | 数据验证库 |
______________________________________________________________________
许可证
这个项目遵循以下许可协议： ISC许可证. 查看 许可证 详情请见。
______________________________________________________________________
相关资源
- 📘 （这个符号本身没有直接的中文翻译，它通常代表一本书或书籍的标志，在中文语境中可以理解为“书”或“书籍”的意思，但具体翻译时可能需要根据上下文来确定更准确的表述。） Teambition开放平台
- 📘（这是一个书籍的符号，通常用于表示书籍或阅读相关的概念，直接翻译可能无法准确传达其含义，但可以理解为“书籍”或“阅读”） Teambition API 文档
- 🔗（这个符号本身在中文中没有直接对应的翻译，它通常表示链接或连接，所以可以翻译为“链接”或根据上下文意译为“连接”等） 模型上下文协议
- 📖 书籍 克劳德代码文档
- 💬
______________________________________________________________________
致谢
感谢Teambition团队提供的开放API，以及Anthropic团队开发的MCP协议。
______________________________________________________________________
作者
这个项目是通过研究官方示例，旨在满足教育和实践目的而创建的。我们希望将Teambition的强大功能无缝融入到日常开发工作流程中。
最后更新时间： 2025年10月23日
______________________________________________________________________
❓ 有问题吗？ 请在GitHub上提交一个问题（或议题）
💡 有什么建议吗？ 欢迎提交拉取请求（Pull Requests）
⭐ 喜欢这个项目吗？ 给我们一个星标！