Planer

Planer MCP Server is an intelligent planning and task management MCP server built with FastMCP. It guides you through context-aware task breakdowns, asks clarifying questions only when needed, and saves well-structured plans with real-time progress updates. Its engineering-focused prompts help with coding, design, testing, and maintenance tasks, while automatically tracking time and storing data in a reliable SQLite database.

How to use

You interact with Planer MCP Server through a compatible MCP client. Create a new plan to generate a detailed set of tasks, guided by smart elicitation and LLM-powered planning. You’ll see real-time progress updates during plan generation, a preview of the proposed plan, and options to accept, modify, or regenerate the plan until you are satisfied. Once confirmed, the plan is saved to the database with time tracking tied to task creation and completion.

Key interaction flow when creating a plan: you start with a title and goals, the system analyzes requirements, asks targeted clarifying questions only if necessary, generates tasks using context-aware prompts, presents a preview, and then saves the plan after your confirmation. If you request changes, the system regenerates with your feedback and refines until you approve. You can then view, filter, and manage plans, including marking tasks as in progress or completed.

How to install

# Prerequisites
# Ensure you have Python and the uv runner available on your system
# Install and run the Planer MCP Server using the recommended UX path

# For Users (with uvx)
uvx planer-mcp

# Optional: add to MCP configuration
# Example JSON snippet for Cursor or similar MCP config
{
  "mcpServers": {
    "planer": {
      "command": "uvx",
      "args": ["planer-mcp"]
    }
  }
}

Development setup can be performed if you want to run and test changes locally. Follow these steps to set up a development environment and run the server directly from source.

# Development setup
cd planer-mcp

uv venv

uv pip install -e ".[dev]"

# Run options
# Run with the MCP runner for end-user testing
uvx planer-mcp

# Or run as a Python module (development)
uv run python -m src.planer_mcp.server

# Or run the main entry point directly
python main.py

Configuration and usage notes

The server exposes an easy-to-use interface for creating and managing plans through standard MCP tooling. You can list plans with pagination, filter to show active work by default, and update the status of individual tasks within a plan. Plans and tasks are stored in a SQLite database for reliable persistence.

To configure the MCP client, include the Planer server in your MCP configuration with the appropriate command and arguments, as shown in the installation section. Use the provided JSON snippet to register the Planer MCP server under a logical name such as planer.

Usage examples and behavior

New plans leverage an intelligent workflow that analyzes requirements, elicits clarification only when needed, generates tasks via LLM sampling, shows a preview for confirmation, and saves the validated plan. You can request modifications and regenerate, with iterative refinement until you are satisfied.

Notes on features and data handling

• Real-time progress reporting during plan creation ensures you stay informed at key milestones (10%, 30%, 60%, 80%, 95%, 100%).
• Time tracking is automatic, based on plan and task creation and completion timestamps.
• Plans can be filtered to hide completed work by default, focusing on active tasks.
• Plans are categorized to apply different planning strategies depending on the task type.

Commands and management

Use the following commands to manage plans and tasks via the MCP interface:

• Create a new plan with title, goal, and category
• List plans with pagination and optional inclusion of completed plans
• Retrieve detailed information about a specific plan
• Update task statuses within a plan
• Update a plan by adding tasks or altering details
• Delete a plan and all its tasks permanently.

Examples of plan lifecycle

• Create a plan for a software feature, review the task list, and confirm to save.
• If the initial plan needs refinement, request modifications and regenerate the task breakdown.
• After validation, the plan is stored and you can monitor progress as tasks move through pending, in_progress, and completed states.

Available tools

new_plan

Creates a new plan with intelligent task breakdown using an LLM-driven workflow, including smart elicitation, task generation, preview, regeneration, and final save.

list_plans

Lists plans with pagination and optional inclusion of completed plans.

get_plan

Retrieves detailed information about a specific plan by plan_id.

update_task_status

Updates the status of one or more tasks within a plan, with optional notes.

update_plan

Updates an existing plan by adding new tasks or changing plan information.

delete_plan

Permanently deletes a plan and all its tasks from the database.