boostu-teamleader-mcp

🔗 BoostU Teamleader MCP

开源的 Teamleader Focus MCP 服务。通过自然语言，在 Claude 和其他 AI 助手中管理你的 CRM。🤖

---

💡 这是什么？

boostu-teamleader-mcp 是一个 Model Context Protocol 服务，可向 AI 助手开放 Teamleader Focus API，包括 Claude Desktop、Claude Code、Cursor 和 Windsurf。它提供 100 多种工具，涵盖 Teamleader Focus 的全部功能：CRM（联系人、公司、交易）、销售文档（报价单、发票、贷项通知单）、产品目录、订阅、项目、时间跟踪、客服工单等。将 AI 连接到它，即可通过自然语言管理整个 CRM。

不想自行托管？

使用托管、全天候在线的版本 teamleader-mcp.boostu.be——无需设置 OAuth，通过魔法链接登录，并提供一键式 Claude 连接器。预览期间免费，之后提供付费套餐。

此仓库包含 MCP 服务开源项目本身：使用你自己的 Teamleader 集成，在本地运行。托管版本在同一服务基础上增加了多租户身份验证、仪表板、使用情况洞察和托管式令牌管理。

	自托管（此仓库）	托管（boostu.be）
价格	免费，采用 MIT 许可证	预览期间免费，之后收费
设置	创建自己的 Teamleader 集成，通过 npx 运行	将一个连接器 URL 复制到 Claude 中
令牌	自行管理 .env 和刷新令牌	为你加密并轮换
适用对象	开发者和自托管用户	非技术团队

---

🔌 工作原理

flowchart LR
    U["🧑 You"] -->|"plain language"| C["🤖 Claude / AI assistant"]
    C <-->|"MCP · stdio"| S["🔗 boostu-teamleader-mcp"]
    S <-->|"OAuth2 REST"| T["📇 Teamleader Focus API"]

你用自然语言向 Claude 提问。Claude 调用此 MCP 服务，通过 OAuth2 向 Teamleader Focus 进行身份验证，并执行相应的 API 调用。你的数据保留在 Teamleader 中；此服务只负责转发调用。

使用此文件右上角的目录按钮可跳转到任意章节。

---

✨ 亮点

• 👥 完整 CRM：在所有销售管道中创建和更新联系人、公司及交易
• 🧾 报价与开票：为交易创建报价单，将发票记入会计账目，通过电子邮件发送，并登记付款
• 📦 产品目录：浏览产品、类别、价目表和计量单位
• 🔁 订阅：创建、更新和停用定期订阅
• 📊 项目与时间跟踪：管理项目和里程碑、记录工时，以及启动/停止实时计时器
• 🎫 客服工单：创建工单、发布回复并更新状态
• 🔎 参考数据查询：查询交易阶段、销售管道、税率、付款期限、失败原因等
• 🔐 支持自动刷新令牌轮换的 OAuth2：令牌会自动刷新；轮换后的令牌会保存到可配置的文件中
• 🧩 可选工具组：通过 TEAMLEADER_TOOLS 仅加载所需工具组，精简助手的上下文

---

🚀 快速开始

无需安装即可运行

npx boostu-teamleader-mcp

全局安装

npm i -g boostu-teamleader-mcp
boostu-teamleader-mcp

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Claude Code

添加到项目的 .mcp.json 或 ~/.claude/mcp.json：

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Cursor

添加到项目根目录下的 .cursor/mcp.json（或全局文件 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

---

🔐 身份验证

你需要三个环境变量：TEAMLEADER_CLIENT_ID、TEAMLEADER_CLIENT_SECRET 和 TEAMLEADER_REFRESH_TOKEN。请在 Teamleader Marketplace / Developer portal 注册集成并完成 OAuth2 授权流程，以获取这些变量。

Teamleader 每次 API 调用都会轮换刷新令牌。请将 TEAMLEADER_TOKEN_STORE 设置为可写文件路径，以便服务在重启之间保存最新令牌；如果不设置，配置中的令牌会在首次重启后失效。

如需查看完整的分步指南（授权 URL、代码交换、辅助脚本），请参阅 docs/AUTHENTICATION.md。

---

⚙️ 配置

环境变量

名称	必需	说明
TEAMLEADER_CLIENT_ID	是	Teamleader 集成的 OAuth2 客户端 ID
TEAMLEADER_CLIENT_SECRET	是	Teamleader 集成的 OAuth2 客户端密钥
TEAMLEADER_REFRESH_TOKEN	是	通过 OAuth2 授权流程获取的初始刷新令牌
TEAMLEADER_TOKEN_STORE	否	服务保存轮换后的刷新令牌的可写文件路径（例如 /var/run/teamleader-token）。强烈建议在生产环境中设置。
TEAMLEADER_TOOLS	否	要启用的工具组键，以逗号分隔。未设置时，将加载全部 21 个组。

选择性启用工具组

使用 TEAMLEADER_TOOLS 限定已注册的工具组。当你想缩小助手的工具列表，或限制其访问 Teamleader 某些区域时，此设置很有用。

TEAMLEADER_TOOLS=deals,quotations,products

组键完整列表：

键	涵盖内容
contacts	联系人增删改查
companies	公司增删改查
deals	交易 / 商机
tasks	任务
events	日历事件
invoices	发票（创建、记账、发送、付款、下载）
quotations	报价单（创建、更新、发送、接受）
products	产品目录和价格表
reference	交易阶段、税率、付款条款等
org	用户、团队、部门
customFields	自定义字段定义
creditNotes	贷项通知单
subscriptions	定期订阅
projects	项目和里程碑
timeTracking	工时记录和实时计时器
activities	通话和会议
tickets	支持工单
tags	为联系人和公司添加 / 移除标签
notes	关于任意主题的备注
files	文件列表、下载、上传
webhooks	Webhook 注册

---

🧰 可用工具

联系人

工具	说明
teamleader_list_contacts	从 Teamleader Focus 列出联系人，支持可选筛选和分页
teamleader_get_contact	获取特定联系人的详细信息
teamleader_create_contact	在 Teamleader Focus 中创建联系人
teamleader_update_contact	更新 Teamleader Focus 中的现有联系人
teamleader_link_contact_to_company	将联系人关联到公司，可选设置职位和决策人标记
teamleader_unlink_contact_from_company	解除联系人与 Teamleader Focus 中公司的关联
teamleader_update_contact_company_link	更新现有联系人—公司关联中的职位或决策人标记

公司

工具	描述
teamleader_list_companies	列出 Teamleader Focus 中的公司，可选择筛选和分页
teamleader_get_company	获取特定公司的详细信息
teamleader_create_company	在 Teamleader Focus 中创建新公司

交易

工具	描述
teamleader_list_deals	列出 Teamleader Focus 中的交易/商机，可选择筛选和分页
teamleader_get_deal	获取特定交易的详细信息
teamleader_create_deal	在 Teamleader Focus 中创建新交易/商机
teamleader_update_deal	更新 Teamleader Focus 中的现有交易

任务

工具	描述
teamleader_list_tasks	列出 Teamleader Focus 中的任务，可选择筛选和分页
teamleader_create_task	在 Teamleader Focus 中创建新任务

事件

工具	描述
teamleader_list_events	列出 Teamleader Focus 中的日历事件，可选择筛选和分页
teamleader_get_event	获取特定事件的详细信息
teamleader_create_event	在 Teamleader Focus 中创建新的日历事件

发票

工具	描述
teamleader_list_invoices	列出 Teamleader Focus 中的发票，可选择筛选和分页
teamleader_get_invoice	获取特定发票的详细信息
teamleader_create_invoice	在 Teamleader Focus 中创建新的发票草稿
teamleader_invoices_book	将发票草稿记入账目并为其分配编号
teamleader_invoices_send	通过电子邮件将发票发送给指定收件人
teamleader_invoices_register_payment	登记发票的付款
teamleader_invoices_download	获取指定格式的发票临时下载 URL

报价单

工具	描述
teamleader_quotations_list	列出报价单，可选择按交易 ID 筛选
teamleader_quotations_info	按 ID 获取单个报价单，可选择同时获取其到期（有效期截止）设置
teamleader_quotations_create	在交易上创建报价单：行项目和/或文本、名称、有效期截止日期
teamleader_quotations_update	更新报价单：行项目、文本、名称或有效期截止日期
teamleader_quotations_accept	接受报价单（标记为已接受——难以撤销）
teamleader_quotations_send	通过电子邮件发送报价单，并自定义主题和消息（抄送、密送、发件人、附件、语言）；#LINK 会替换为签署链接

产品

工具	描述
teamleader_products_list	列出产品，可选择按搜索词筛选
teamleader_products_info	按 ID 获取单个产品
teamleader_product_categories_list	列出产品类别
teamleader_price_lists_list	列出价目表
teamleader_units_of_measure_list	列出计量单位

参考数据

工具	描述
teamleader_deal_phases_list	列出交易阶段
teamleader_deal_pipelines_list	列出交易管道
teamleader_deal_sources_list	列出交易来源
teamleader_lost_reasons_list	列出交易失败原因
teamleader_tax_rates_list	列出税率
teamleader_payment_terms_list	列出付款条款
teamleader_withholding_tax_rates_list	列出预扣税税率

组织

工具	描述
teamleader_users_list	列出用户，可选择按搜索词筛选
teamleader_users_info	按 ID 获取单个用户
teamleader_users_me	获取当前已通过身份验证的用户
teamleader_teams_list	列出团队
teamleader_departments_list	列出部门

自定义字段

工具	描述
teamleader_custom_field_definitions_list	列出自定义字段定义
teamleader_custom_field_definitions_info	根据 ID 获取单个自定义字段定义

贷项通知单

工具	描述
teamleader_credit_notes_list	列出贷项通知单，可按发票或部门筛选
teamleader_credit_notes_info	根据 ID 获取单个贷项通知单

订阅

工具	描述
teamleader_subscriptions_list	列出订阅，可按客户筛选
teamleader_subscriptions_info	根据 ID 获取单个订阅
teamleader_subscriptions_create	创建新订阅（开始为客户定期开发票）
teamleader_subscriptions_update	更新订阅标题
teamleader_subscriptions_deactivate	停用订阅（停止后续开票）

项目

工具	描述
teamleader_projects_list	列出项目，可按搜索词或客户筛选
teamleader_projects_info	根据 ID 获取单个项目
teamleader_projects_create	为客户创建新项目
teamleader_milestones_list	列出里程碑，可按项目筛选
teamleader_milestones_create	在项目中创建里程碑

时间跟踪

工具	描述
teamleader_time_tracking_list	列出时间跟踪条目，可按用户筛选
teamleader_time_tracking_add	添加时间跟踪条目
teamleader_time_tracking_update	更新时间跟踪条目的时长或描述
teamleader_timer_start	启动计时器
teamleader_timer_stop	停止计时器并创建时间跟踪条目

活动（通话和会议）

工具	描述
teamleader_calls_list	列出通话，可按客户筛选
teamleader_calls_create	创建通话活动
teamleader_calls_complete	将通话标记为已完成
teamleader_meetings_list	列出会议
teamleader_meetings_create	安排会议
teamleader_meetings_complete	将会议标记为已完成

工单

工具	描述
teamleader_tickets_list	列出支持工单，可按客户或状态筛选
teamleader_tickets_info	根据 ID 获取单个支持工单
teamleader_tickets_create	为客户创建新的支持工单
teamleader_tickets_update	更新工单主题或状态
teamleader_tickets_add_message	在工单对话串中添加回复或消息
teamleader_ticket_status_list	列出所有可用的工单状态

标签

工具	描述
teamleader_contacts_add_tags	为联系人添加一个或多个标签
teamleader_contacts_remove_tags	从联系人移除一个或多个标签
teamleader_companies_add_tags	为公司添加一个或多个标签
teamleader_companies_remove_tags	从公司移除一个或多个标签

备注

工具	描述
teamleader_notes_list	列出关联到某个对象（联系人、公司、交易等）的备注
teamleader_notes_create	创建关联到某个对象的备注

文件

工具	描述
teamleader_files_list	列出关联到某个对象（联系人、公司、交易等）的文件
teamleader_files_download	根据文件 ID 获取临时下载 URL
teamleader_files_upload	启动两步文件上传并返回上传 URL

Webhooks

工具	描述
teamleader_webhooks_list	列出已注册的 Webhook
teamleader_webhooks_register	为指定事件类型注册 Webhook URL
teamleader_webhooks_unregister	为指定事件类型注销 Webhook URL

---

💬 示例提示词

Create a quotation for deal <id> with two line items: 5 hours of consulting at €150/h and a one-time setup fee of €500.

Move the valid-until date of quotation <id> to the end of next month, then email the customer a reminder in Dutch with the signing link.

Book the draft invoice <id> into accounting and then send it to the customer.

Register a €1 200 payment against invoice <id> received today via bank transfer.

Log 2.5 hours on project <id> for user <user_id> with the note "API integration work".

Start a timer for me right now — I'm working on the BoostU onboarding project.

Open a support ticket for company <id>: subject "Login not working", priority high.

What deal phase IDs do we have in pipeline <id>? I need to move deal <id> to the "Proposal sent" phase.

List all products in the "Hosting" category and their prices.

Create a monthly subscription for company <id>: product <product_id>, quantity 1, starting next month.

Show me all open deals with their current phases and tell me which ones haven't moved in the last 30 days.

---

🐳 Docker

docker run --rm \
  -e TEAMLEADER_CLIENT_ID=your-client-id \
  -e TEAMLEADER_CLIENT_SECRET=your-client-secret \
  -e TEAMLEADER_REFRESH_TOKEN=your-refresh-token \
  -e TEAMLEADER_TOKEN_STORE=/data/teamleader-token \
  -v /var/run/teamleader:/data \
  ghcr.io/boostuagency/boostu-teamleader-mcp

---

🛠️ 开发

# Clone and install
git clone https://github.com/boostuagency/boostu-teamleader-mcp.git
cd boostu-teamleader-mcp
npm install

# Run in development mode (no build step required)
npm run dev

# Build
npm run build

# Run tests
npm test

# Type-check only
npm run typecheck

---

🏗️ 架构

服务的核心是 src/server.ts 中的 createServer，它与传输方式无关——接收一个 TeamleaderClient，注册已启用的工具组，并返回一个普通的 McpServer 实例；入口文件（src/index.ts）会将其连接到 StdioServerTransport。工具逻辑位于 src/tools/ 下按领域划分的模块中，每个模块都遵循一致的 try / respond / catch / respondError 模式，并使用 src/lib/ 中的共享辅助函数。OAuth2 令牌的获取和轮换完全由 src/api/auth.ts 负责，对代码库的其他部分透明。此服务的托管式多租户版本可通过 teamleader-mcp.boostu.be 使用。

---

✅ 端点验证

大多数读取端点（*.list、*.info）均已通过 Teamleader Focus API 的实时验证。若干写入和操作端点（例如 subscriptions.create、projects.create、files.upload）依据官方文档实现，但尚未使用启用了相关模块的实际账户进行测试。如果端点名称有误，调用会返回明确的 HTTP 错误消息，而不会悄无声息地出错。完整的端点清单和验证状态记录在 docs/teamleader-endpoints.md 中。

---

🤝 贡献

有关开发环境配置、提交规范以及添加新工具组的说明，请参阅 CONTRIBUTING.md。

---

🔒 安全

请将安全漏洞报告发送至 [email protected]——请勿创建公开议题。披露政策请参阅 SECURITY.md。切勿将 .env 文件或 .teamleader-token 提交到版本控制中；这两个文件均已列入 .gitignore。

---

⚖️ 免责声明

这是一个独立的社区集成项目，与 Teamleader NV 没有关联，也未获得其认可或赞助。“Teamleader”和“Teamleader Focus”是 Teamleader NV 的商标，此处仅用于说明兼容性。您须根据 Teamleader 的条款自行负责使用 Teamleader API。

---

📄 许可证

MIT License — Copyright (c) 2026 BoostU Agency。上游归属信息请参阅 NOTICE。