打开2.0 MCP服务器

连接到Toggl 2.0 API的本地MCP（模型上下文协议）服务器。工作与任何MCP客户端，包括克劳德代码和克劳德桌面。

服务器支持MCP 2026-07-28 并保持与传统MCP客户端的兼容性。JSON工具结果包括 structuredContent 对于现代客户端和旧客户端的文本回退。

一键式安装

第一次使用时，叫 身份验证 登录MCP工具（打开浏览器）。有关Claude Code和Claude Desktop，请参见 添加到您的MCP客户端 下面。

安装

npm install @togglhq/mcp
# or: pnpm add @togglhq/mcp

验证一旦MCP服务器连接-调用 身份验证 工具（打开浏览器）。或者从终端：

npx @togglhq/mcp auth

对于没有本地安装的一次性运行： npx -y @togglhq/mcp auth.

添加到您的MCP客户端

克劳德代码

claude mcp add toggl-focus -- npx @togglhq/mcp

克劳德桌面

添加到您的Claude Desktop配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "toggl-focus": {
      "command": "npx",
      "args": ["@togglhq/mcp"]
    }
  }
}

保存后重新启动Claude Desktop。

身份验证

用途 OAuth2与PKCE 通过Toggl帐户服务。凭据存储在 ~/.toggl/focus-tools.json (0600)模式。访问令牌自动刷新-调用 身份验证 再次（或运行） npx @togglhq/mcp auth)来切换工作区，或者如果刷新令牌过期（在4周不活动之后）。

从旧版本升级？ 先前存储在 ~/.toggl-focus-mcp/config.json 仍然自动读取-不需要重新身份验证。

统一配置与遗留文件： MCP 注销 下存在匹配的配置文件行时才删除凭据 ~/.toggl/focus-tools.json 与 active.mcp 集。呼叫 auth 一次迁移到统一文件，如果注销报告没有清除任何内容(或运行 npx @togglhq/mcp auth 从终端)。

CI或无头环境

集 TOGGL_API_TOKEN 到个人Toggl API密钥(toggl_sk_…，来自Toggl 2.0 设置→API令牌）. 它优先于任何OAuth配置文件：不打开浏览器，不刷新，也不写入任何内容 ~/.toggl/focus-tools.json.

claude mcp add toggl-focus \
  -s user \
  -e TOGGL_API_TOKEN=<your-api-key> \
  -e TOGGL_ORGANIZATION_ID=<your-org-id> \
  -- npx @togglhq/mcp

API密钥不能列出组织，所以设置 TOGGL_ORGANIZATION_ID 除非应用上面的默认值。读取应用程序url focus.toggl.com/<organization_id>/workspaces/<workspace_id>/…。服务器在启动时检查密钥和组织/工作空间对，并按名称报告已撤销的密钥或丢失的组织成员。

API密钥只能到达Toggl 2.0 API。调用Toggl帐户的工具返回 requires OAuth sign-in (run auth) 在此模式下： org-invitations， org-members， org-time-off-me， org-workspaces， shared-holidays， shared-status， shared-working-hours, workspace-list 与 refresh: true. workspace-switch， profile-switch 和 profile-remove 残疾，以及 auth， logout 和 profile-list 报告令牌模式，而不是触摸保存的配置文件。要使用这些工具，请取消设置 TOGGL_API_TOKEN 和运行 npx @togglhq/mcp auth.

这个 toggl CLI (@togglhq/cli)尊重相同的变量； --workspace-id 覆盖 TOGGL_WORKSPACE_ID 在那里。该键永远不会被记录，并从错误报告中删除。

工具

实体工具

每个领域一个工具(例如 tasks， projects， time-entries， organization）. 每个工具接受：

• action (必需)
• data (可选)
• confirm_token （可选）-修改操作的第二步
• dry_run （可选）-验证输入而不调用API

突变的确认: 变异工具返回 confirm_required 与一个 confirm_token 第一次打电话；重复与 confirm_token 来执行。

工作区、概要文件和授权

• workspace-list -列出工作空间(refresh: true 从帐目中取回)
• workspace-switch -设置活动工作区
• 文件列表， profile-switch， profile-remove ——管理 active.mcp 在 ~/.toggl/focus-tools.json
• 身份验证， 注销 -登录或清除主MCP配置文件

面向代理的引导船进入 skills/toggl-mcp/SKILL.md 在这个包裹里。

隐私和分析

公共构建可以发送产品分析：工具名称，实体-工具 action (例如 list)，结果(success， error，或者 confirmation_required)、客户端、会话id和包版本。工具参数和结果永远不会被收集。登录会话由您的Toggl帐户id标识，因此每次重复使用不会被计算为新用户；未经身份验证的进程保持匿名。

禁用产品分析：

TOGGL_PRODUCT_ANALYTICS=off

默认情况下，错误报告是打开的。它发送工具名称、编校的错误类别、带有包相关文件路径的堆栈跟踪、MCP、Node和OS版本，以及不带查询字符串的采样请求时间。它从不发送工具参数、结果、异常文本、控制台输出、主机名、本地路径或项目的依赖项列表。使用以下命令禁用它 TOGGL_SENTRY=off，或将其发送到您自己的哨兵项目 TOGGL_SENTRY_DSN.

许可证

专有的Toggl软件。看到 许可证 和 切换法律条款.