TaskQueue MCP server for AI agents

This MCP Task Manager serves as a structured task management system for AI assistants, helping them handle multi-step tasks with optional user approval checkpoints, progress tracking, and task visualization.

Installation and Setup

Basic Setup

To use the MCP Task Manager in Claude Desktop, Cursor, or another MCP client, configure it as follows:

{
  "tools": {
    "taskqueue": {
      "command": "npx",
      "args": ["-y", "taskqueue-mcp"]
    }
  }
}

For CLI access, you can run:

npx taskqueue --help

Alternatively, install the package globally:

npm install -g taskqueue-mcp

Advanced Configuration

The task manager supports multiple LLM providers for generating project plans. Configure one or more of these environment variables:

export OPENAI_API_KEY="your-api-key"
export GOOGLE_GENERATIVE_AI_API_KEY="your-api-key"
export DEEPSEEK_API_KEY="your-api-key"

Or include them in your MCP client configuration:

{
  "tools": {
    "taskqueue": {
      "command": "npx",
      "args": ["-y", "taskqueue-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "GOOGLE_GENERATIVE_AI_API_KEY": "your-api-key",
        "DEEPSEEK_API_KEY": "your-api-key"
      }
    }
  }
}

Using the Task Manager

Available MCP Tools

Project Management Tools

list_projects: Lists all projects in the system
read_project: Gets details about a specific project
create_project: Creates a new project with initial tasks
delete_project: Removes a project
add_tasks_to_project: Adds new tasks to an existing project
finalize_project: Finalizes a project after all tasks are done

Task Management Tools

list_tasks: Lists all tasks for a specific project
read_task: Gets details of a specific task
create_task: Creates a new task in a project
update_task: Modifies a task's properties
delete_task: Removes a task from a project
approve_task: Approves a completed task
get_next_task: Gets the next pending task in a project
mark_task_done: Marks a task as completed with details

Task Status and Workflows

Tasks have three possible statuses:

not started: Task has not been started yet
in progress: Task is currently being worked on
done: Task has been completed (requires completedDetails)

Tasks follow specific transition rules:

From not started: Can only move to in progress
From in progress: Can move to either done or back to not started
From done: Can move back to in progress if additional work is needed

Typical Workflow

create_project: Start a project with initial tasks
get_next_task: Get the first pending task
Work on the task
mark_task_done: Mark the task as complete with details
Wait for approval (if manual approval is enabled)
get_next_task: Get the next pending task
Repeat steps 3-6 until all tasks are complete
finalize_project: Complete the project

CLI Commands

Task Approval

By default, tasks and projects are auto-approved. For manual approval:

npx taskqueue approve-task -- <projectId> <taskId>

Options:

-f, --force: Force approval even if the task is not marked as done

Listing Tasks and Projects

List all projects and tasks:

npx taskqueue list-tasks

View a specific project:

npx taskqueue list-tasks -- -p <projectId>

Data Storage

The task manager stores data in a JSON file at the following default locations:

Linux: ~/.local/share/taskqueue-mcp/tasks.json
macOS: ~/Library/Application Support/taskqueue-mcp/tasks.json
Windows: %APPDATA%\taskqueue-mcp\tasks.json

To use a custom file path (not recommended), set the TASK_MANAGER_FILE_PATH environment variable:

{
  "tools": {
    "taskqueue": {
      "command": "npx",
      "args": ["-y", "taskqueue-mcp"],
      "env": {
        "TASK_MANAGER_FILE_PATH": "/path/to/tasks.json"
      }
    }
  }
}

For CLI access to the same custom file:

export TASK_MANAGER_FILE_PATH="/path/to/tasks.json"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "taskqueue" '{"command":"npx","args":["-y","taskqueue-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "taskqueue": {
            "command": "npx",
            "args": [
                "-y",
                "taskqueue-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "taskqueue": {
            "command": "npx",
            "args": [
                "-y",
                "taskqueue-mcp"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect