# @togglhq/mcp 中文文档

规范地址：https://npmcn.com/package/%40togglhq/mcp/

版本：1\.13\.127
npm 元数据更新时间：2026-11-02T15:23:59.134Z
中文译文更新时间：2026-11-02T17:07:41.236Z
软件包许可：UNLICENSED

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40togglhq/mcp
原文对照：https://npmcn.com/package/%40togglhq/mcp/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.7 MB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-07-05T06:58:56.404Z
- 最新版本发布：2026-11-02T15:23:58.910Z
- 已发布版本数：448（近 12 个月 448 个）

## 中文简介

Toggl 2.0 MCP服务器，用于Claude Code， Claude Desktop和其他MCP客户端。

## 安装

```sh
npm install @togglhq/mcp
```

也可以使用：`pnpm add @togglhq/mcp`、`yarn add @togglhq/mcp`、`bun add @togglhq/mcp`

## README

# 打开2.0 MCP服务器

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

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

## 一键式安装

[![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=toggl&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40togglhq%2Fmcp%22%5D%2C%22env%22%3A%7B%7D%7D) [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=toggl&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB0b2dnbGhxL21jcCJdfQ%3D%3D)

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

## 安装

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

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

```bash
npx @togglhq/mcp auth
```

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

## 添加到您的MCP客户端

### 克劳德代码

```bash
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`

```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`.

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

| 变量 | 要求 | 未设置时的默认值 |
| --- | --- | --- |
| `TOGGL_API_TOKEN` | 是 | 从 `auth` |
| `TOGGL_ORGANIZATION_ID` | 通常 | 在Toggl的托管MCP中最后选择的组织，如果它用于相同的工作空间；否则是错误 |
| `TOGGL_WORKSPACE_ID` | 否 | 您当前的Toggl 2.0工作区 |
| `TOGGL_USER_ID` | 否 | 从API键中查找 |

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标识，因此每次重复使用不会被计算为新用户；未经身份验证的进程保持匿名。

禁用产品分析：

```bash
TOGGL_PRODUCT_ANALYTICS=off
```

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

## 许可证

专有的Toggl软件。看到 [许可证](https://npmcn.com/package/%40togglhq/mcp/LICENSE) 和 [切换法律条款](https://toggl.com/legal/).

## 常见问题

### @togglhq/mcp 是什么？

Toggl 2\.0 MCP服务器，用于Claude Code， Claude Desktop和其他MCP客户端。

### 如何安装 @togglhq/mcp？

在项目目录运行 npm install @togglhq/mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp、toggl-mcp，可以用 npx mcp 直接运行。

### @togglhq/mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @togglhq/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @togglhq/mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @togglhq/mcp 可以商用吗？

@togglhq/mcp 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @togglhq/mcp 还在维护吗？

最新版本 1\.13\.127 发布于 2026/11/02（今天）；至今共发布 448 个版本，其中过去 12 个月发布了 448 个；首次发布于 2026/07/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。