# Toggl 2.0 MCP Server

A local MCP (Model Context Protocol) server that connects to the Toggl 2.0 API. Works with any MCP client including Claude Code and Claude Desktop.

## One-click install

[![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)

On first use, call the **auth** MCP tool to sign in (opens your browser). For Claude Code and Claude Desktop, see **Add to your MCP client** below.

## Install

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

Authenticate once the MCP server is connected — call the **auth** tool (opens your browser). Or from a terminal:

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

For one-off runs without a local install: `npx -y @togglhq/mcp auth`.

## Add to your MCP client

### Claude Code

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

### Claude Desktop

Add to your Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

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

Restart Claude Desktop after saving.

## Authentication

Uses **OAuth2 with PKCE** via the Toggl Accounts service. Credentials are stored in `~/.toggl/focus-tools.json` (mode 0600). Access tokens refresh automatically — call **auth** again (or run `npx @togglhq/mcp auth`) to switch workspaces or if your refresh token expires (after 4 weeks of inactivity).

> **Upgrading from an older version?** Sessions previously stored at `~/.toggl-focus-mcp/config.json` are still read automatically — no re-authentication needed.

> **Unified config vs legacy file:** MCP **logout** only removes credentials when there is a matching profile row under **`~/.toggl/focus-tools.json`** with **`active.mcp`** set. Call **`auth`** once to migrate into the unified file if logout reports nothing was cleared (or run `npx @togglhq/mcp auth` from a terminal).

### CI or headless environments

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

## Tools

### Entity tools

One tool per domain (for example `tasks`, `projects`, `time-blocks`, `time-entries`, `organization`). Each tool accepts:

- **`action`** (required)
- **`data`** (optional)
- **`confirm_token`** (optional) — second step for mutating operations
- **`dry_run`** (optional) — validates input without calling the API

**Mutation confirmation:** mutating tools return `confirm_required` with a `confirm_token` on the first call; repeat with `confirm_token` to execute.

### Workspace, profiles, and auth

- **workspace-list** — list workspaces (`refresh: true` refetches from Accounts)
- **workspace-switch** — set the active workspace
- **profile-list**, **profile-switch**, **profile-remove** — manage `active.mcp` in `~/.toggl/focus-tools.json`
- **auth**, **logout** — sign in or clear the active MCP profile

Agent-oriented guidance ships in `skills/toggl-mcp/SKILL.md` inside this package.

## License

Proprietary Toggl software. See [LICENSE](LICENSE) and [Toggl legal terms](https://toggl.com/legal/).