# Toggl Plan MCP

> Toggl Plan MCP Server gives your AI agent direct control over team timelines, milestones, and workloads. Instead of clicking through complex dashboards, you can list projects, create new tasks, update deadlines, or check resource availability just by asking. It turns project planning into a conversation.

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

## Description

This server gives your AI agent direct control over every moving part of your team's project plan, bypassing those clunky dashboards entirely. You don't gotta click through deep menus to manage timelines or check resource capacity; you just talk to your agent and it handles the heavy lifting. It turns complex project management into a simple conversation.

### Project Structure & Scope Management

Your agent can give you an immediate view of everything running in the workspace. You'll get a complete list of every active project, which `list_workspace_projects` pulls for you. Need to know what kind of work gets done? `list_workspace_tags` provides a full directory of all standardized tags used to categorize tasks across your board. When it comes to people, `list_workspace_members` gathers a comprehensive directory of every user registered in the workspace so you can assign work or check capacity.

### Reading and Viewing Timelines

You'll never have to manually build a date range view again. The tool that calls `get_timeline_view` retrieves a complete visual breakdown of all tasks and milestones falling within specific dates. If you only care about the major checkpoints, `list_milestones` displays every milestone marker currently set up on the project timeline. For deep dives into just one piece of work, `get_task_details` pulls all specific data points for an identified task.

### Controlling Task Lifecycles

This is where you take control. Your agent can create new tasks using `create_timeline_task`, scheduling a brand-new segment on the timeline with precise start and end dates. You can also modify existing work; `update_timeline_task` lets your agent change details for any current task by providing updated data in JSON format. If a task is outdated or finished, you don't gotta worry about it hanging around—calling `delete_timeline_task` permanently removes that entry from the timeline.

### Combining Tools into Workflow

Your agent handles everything: It can pull all available tags (`list_workspace_tags`), check every active project (`list_workspace_projects`), and list every user on the team (`list_workspace_members`). You can then tell it to create a milestone using `create_milestone`, or schedule an initial task segment that gets pulled into a timeline view via `get_timeline_view`. It gives you granular control to update those tasks, making sure your project data is always current and actionable. This means if you need to see what's happening in Q3, it pulls the right data; if you need to move a deadline, it updates the record. You keep everything organized without touching the graphical interface.

## Tools

### create_milestone
Adds a new milestone marker to the project timeline.

### create_timeline_task
Schedules a brand-new task segment on the timeline using specified start and end dates.

### delete_timeline_task
Permanently removes an existing, completed, or deprecated task from the timeline.

### get_task_details
Pulls all specific data points for a single, identified task on the timeline.

### get_timeline_view
Retrieves a complete visual view of the timeline tasks that fall within a defined date range.

### list_milestones
Displays a list of every milestone marker currently set up on the project timeline.

### list_workspace_members
Retrieves a full directory of all people registered in the current workspace.

### list_workspace_projects
Lists every active project and its status within the entire workspace.

### list_workspace_tags
Retrieves a list of all available tags used to categorize tasks across the board.

### update_timeline_task
Modifies an existing task on the timeline by providing updated data in a JSON format.

## 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

### View Timeline Structure
Retrieve a date-specific view of all active tasks and milestones within the workspace.

### Manage Projects and Tags
List every project currently running in the workspace or check the available standardized tags for categorization.

### Task Lifecycle Control
Create new tasks on the timeline, update existing task details (like dates), or permanently remove outdated entries.

### Resource and Team Overview
List all registered users in the workspace to help assign work or track capacity.

## Use Cases

### Kick-off Review: What are we building?
The Project Manager needs to start a review. They ask the agent to run `list_workspace_projects`. The agent responds with a clean list, allowing them to confirm the scope before drafting any new tasks.

### Scope Creep Mitigation: Adding an emergency task.
An urgent bug fix is needed. Instead of opening the project and searching for the right spot, the agent runs `create_timeline_task`, automatically scheduling the 'Bug Fix' segment with start/end dates.

### Resource Reallocation: Who has capacity?
The team lead needs to move work from one person to another. They run `list_workspace_members` and cross-reference the output against known milestones, finding who is underutilized and where they can help.

### End of Cycle Cleanup: Archiving old tasks.
The team finishes a module. Instead of clicking through to find the task ID and deleting it, the agent uses `delete_timeline_task` with simple confirmation instructions, keeping the timeline clean.

## Benefits

- Instant visibility into the whole project scope. Instead of clicking through multiple menus, running `list_workspace_projects` gives you an immediate list of everything the team is tackling right now.
- Never lose track of a key deliverable. You can use `list_milestones` to pull up every major checkpoint on the timeline in seconds—no dashboard searching required.
- Keep your data current, instantly. When a date shifts or a task finishes early, use `update_timeline_task` through chat instead of manually editing the GUI.
- Manage capacity without leaving your terminal. Use `list_workspace_members` to get user directories and check who needs work assignment right now.
- Task management in one flow. You can complete the full task cycle—create with `create_timeline_task`, read details with `get_task_details`, and delete old ones with `delete_timeline_task`—all via simple instructions.

## How It Works

The bottom line is: you use natural language to execute complex, multi-step project management commands that would otherwise require clicking through multiple menus.

1. Subscribe your AI client to this server component and input your specific Toggl Plan API Token.
2. Instruct your agent with a command, like 'List all active projects in Workspace X' or 'Create milestone Y for Q3'.
3. The server executes the required tool (e.g., `list_workspace_projects`), returns structured data, and lets your AI client complete the action.

## Frequently Asked Questions

**How do I list projects using list_workspace_projects?**
You ask your agent to run `list_workspace_projects`. The server returns a clean list containing the name and ID for every active project in the workspace. This is perfect for starting any new task flow.

**What if I need to change an existing date? Do I use update_timeline_task?**
Yes, you must use `update_timeline_task`. You'll need the original Task ID and the updated JSON payload for the dates. Always confirm the task exists first using `get_task_details`.

**How many milestones can I see with list_milestones?**
The tool simply lists all existing milestone markers, regardless of how many there are. It's a quick way to audit the high-level checkpoints for any given project.

**Can I add a new task on the timeline using create_timeline_task?**
Absolutely. You must provide three key pieces of information: the name, the start date (YYYY-MM-DD), and the end date (YYYY-MM-DD). The tool then creates the segment for you.

**What happens if I use delete_timeline_task? Is this permanent?**
Yes, deleting a task is irreversible. The server permanently removes that entry from the timeline immediately upon execution. Use it carefully when you're absolutely sure the work segment is obsolete.

**If I run get_task_details, what specific data points can I retrieve for a single timeline task?**
You get comprehensive details about that single task, including its name, start date, and end date. This function provides the core metadata needed to understand the segment's scope.

**How does list_workspace_members help me manage team capacity?**
It returns a full directory of every registered user in your workspace. You use this list to verify who needs tasks assigned or whose bandwidth you need to check against project goals.

**When using get_timeline_view, what format do I provide for the date range?**
You must specify both a 'since' and an 'until' date in YYYY-MM-DD format. This limits the view to only tasks that fall within that precise operational window.

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