# Toggl Plan MCP

> Toggl Plan lets your AI agent manage complex project timelines directly from a chat window. It handles creating tasks, listing milestones, updating resource workloads, and checking user roles—all without you needing to click through Toggl's graphical interface. Your agent acts like an API wrapper for all core planning functions, letting PMs keep their workflow inside their conversation.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** timeline-planning, capacity-tracking, resource-management, milestones, workload-balancing, project-scheduling

## Description

This server gives your AI client direct access to Toggl Plan data. Forget clicking through the clunky web UI just to run a few queries or make some changes. Your agent acts like an API wrapper for all core planning functions, letting you manage complex project timelines right from your chat window.

**Project Visibility & Status Checks**

Your AI client can pull key structural data first. You can ask it to retrieve a directory listing of every active project within the designated workspace using `list_workspace_projects`. Want to know what big markers are set? It'll grab a complete list of defined project milestones via `list_milestones`. If you need specifics on one particular job, your agent runs `get_project_details` for that targeted Project ID. For an overview of everything currently running in the space, it pulls all tasks using `list_timeline_tasks`. You can also check what tags are available to keep things consistent by calling `list_workspace_tags`, and if you need to track down the specifics on one node, `get_task_details` provides all the metadata and status info for that specific task.

**Managing Tasks & Timelines**

The agent handles the full lifecycle of a project task. Need a new step added? You use `create_timeline_task`, feeding it the required Workspace ID, Task Name, and Project ID to add a fresh node onto the timeline. If that task is obsolete or needs removing, you can permanently delete it using `delete_timeline_task`—just remember, that action cannot be undone. To keep records current when details change, your agent modifies an existing entry with `update_timeline_task`; this requires you to feed all updates as a structured JSON object.

**Team and Resource Management**

Managing people is just as easy. For resource planning, it pulls a directory of every user account that has access to the workspace ID using `list_workspace_users`. When you need project specifics for one job, you can also fetch detailed information about that single Project ID with `get_project_details`.

Your agent handles everything from listing team users and checking available tags to building new tasks directly into the timeline. It keeps your workflow contained inside your conversation so you never have to leave your terminal.

## Tools

### create_timeline_task
Adds a new task node onto the project timeline. Requires the workspace ID, task name, and project ID.

### delete_timeline_task
Permanently removes a task from the timeline. This action cannot be undone.

### get_project_details
Retrieves specific data points for a single, targeted project ID within Toggl Plan.

### get_task_details
Pulls all the metadata and status information for one specific timeline task.

### list_milestones
Retrieves a comprehensive list of every defined project milestone in the workspace.

### list_timeline_tasks
Lists all tasks in a given workspace ID, providing an overview of everything currently scheduled.

### list_workspace_projects
Retrieves a directory listing of every active project within the designated Toggl Plan workspace.

### list_workspace_tags
Checks and lists all available tags used to categorize tasks in the workspace, ensuring consistency.

### list_workspace_users
Provides a full list of every user account that has access to the workspace for resource tracking.

### update_timeline_task
Modifies an existing timeline task's details. You must provide all updates as a JSON object.

## Prompt Examples

**Prompt:** 
```
List all active projects in Workspace 992211.
```

**Response:** 
```
I've retrieved 2 active projects in workspace 992211:
- Name: 'Q4 Product Roadmap', Project ID: 19332
- Name: 'Legacy API Migration', Project ID: 19445
```

**Prompt:** 
```
Create a timeline task named 'Re-authenticate module' in Project 19332, workspace 992211.
```

**Response:** 
```
The timeline task 'Re-authenticate module' has been successfully created under project 19332. New Task ID: 52003.
```

## Capabilities

### List Project Milestones
The agent retrieves a list of all defined project milestones for immediate visibility.

### Get Workspace Tasks
It lists every task within a specific workspace, giving you an overview of the current workload.

### Create New Task Nodes
You can generate and add a new project task directly to the timeline using simple parameters.

### Update Existing Tasks
The agent modifies an existing timeline entry by accepting data updates, keeping records current.

### List Team Users
It pulls a directory of all registered users tied to the specific workspace ID for resource planning.

## Use Cases

### Onboarding a New Feature
The PM needs to know if the new 'API Gateway' project is ready. They ask their agent: 'What projects are active in Workspace 992211?'. The agent runs `list_workspace_projects`, instantly listing all candidates, allowing the PM to immediately run `get_project_details` on the correct ID without searching.

### End-of-Week Workload Audit
A team lead needs a quick audit of who logged hours. They instruct the agent to list all users via `list_workspace_users`. Then, they use this user directory to check specific task workloads using `list_timeline_tasks` for capacity checks.

### Quick Task Correction
A developer realizes a deadline is wrong. Instead of finding the old task and editing it, they send: 'Update task ID 52003 with new due date.' The agent uses `update_timeline_task` immediately, correcting the timeline without manual steps.

### Checking Dependencies
The team is starting Phase 2. A PM asks: 'What milestones must be hit before we start?' The agent calls `list_milestones`, providing a definitive checklist of required deliverables and their status.

## Benefits

- **Full Task Lifecycle Control:** Instead of manually logging into Toggl to create or update a task, use `create_timeline_task` or `update_timeline_task`. Your agent handles the JSON object passing—you just talk to it. This keeps you in your chat environment.
- **Instant Project Visibility:** Need to know what's running? Running `list_workspace_projects` pulls all active project segments directly into your conversation, saving you from navigating multiple dashboards.
- **Resource Allocation Check:** Stop guessing who has capacity. Use `list_workspace_users` and cross-reference user lists against milestones found via `list_milestones`. You can assign work accurately every time.
- **Deep Metadata Dive:** Don't just get a list—get details. Run `get_project_details` or `get_task_details` to pull specific data points, like due dates or assigned owners, for critical follow-ups.
- **Data Standardization:** Before you build anything, check the rules. Running `list_workspace_tags` ensures your team uses standardized labels, so your reports don't get messy.

## How It Works

The bottom line is that your AI client acts as a direct command-line interface to Toggl Plan's core scheduling functions, bypassing the UI entirely.

1. First, subscribe your AI client to this component and provide it with your Toggl Plan API Token.
2. Next, instruct your agent using a plain language query. For example: 'List all active projects in workspace 992211.'
3. The agent executes the necessary tool calls, processes the data (e.g., `list_workspace_projects`), and returns structured results you can use immediately.

## Frequently Asked Questions

**How do I list all projects using the Toggl Plan MCP Server?**
Use the `list_workspace_projects` tool. This requires specifying the workspace ID. It returns a full directory of every active project name and its associated ID.

**Can I update an old task using `update_timeline_task`?**
Yes, but you must provide the current Task ID for it to work. You'll need to run `get_task_details` first to grab that unique ID and verify its existence.

**Does Toggl Plan MCP Server help me assign work?**
It helps you plan the assignment. Run `list_workspace_users` to see available people, then use task tools like `create_timeline_task` to attach the workload to a specific person.

**What if I delete a task using `delete_timeline_task`?**
The deletion is permanent. The tool provides no undo function, so always confirm with your team before running this action.

**How do I set up authentication for `list_timeline_tasks`?**
You provide your API Token and workspace ID during setup. The agent uses these credentials to authorize all read operations, ensuring the tasks listed belong to the correct workspace.

**How does the `list_workspace_tags` tool help me maintain standardized labeling?**
It retrieves every current tagging structure used in your workspace. This lets you check existing labels before creating new ones, which prevents data inconsistencies and ensures uniform categorization.

**What happens if I use `get_task_details` with an incorrect Task ID?**
The system returns a specific error message indicating the task was not found. This stops the agent from attempting to process invalid data, keeping your workflow accurate.

**How do I use `list_milestones` to map out high-level project goals?**
It retrieves a list of all defined project milestones across your workspace. This gives you the top-tier checkpoints so your agent can schedule tasks against major, long-term deliverables.

**Where do I obtain my Toggl Plan Access Token?**
Navigate to the Toggl Plan web panel, head over to your **Profile settings**, and locate the Developer/API Integrations segment. You will need a valid Access Token (often labeled API or OAuth Bearer token in your administrative view). Create it permanently and keep the exposed hash secure.

**Does the system support permanent deletion of elements?**
Yes. This connector features a `delete_timeline_task` handler. If specifically instructed by you, the AI agent is capable of making a permanent removal request which cannot be un-done. You should instruct the AI cautiously when using mutations.

**Are there any data sync delays when updating timelines with the agent?**
No. Toggl Plan's API ensures immediate reflection of all timeline and milestone changes. When the agent updates a task or resource allocation, it instantly appears in the web interface for all workspace users without any caching delays.