Task Manager MCP server

This server integrates Cursor AI with a task management system to enhance its capabilities through a Model Context Protocol (MCP) implementation. It overcomes context window limitations while providing a visual task management interface.

Installation

Prerequisites

• Node.js
• npm
• Git

Setting Up the Server

1. Clone the repository:

   git clone https://github.com/jhawkins11/task-manager-mcp.git
   cd task-manager-mcp
   

2. Install dependencies:

   npm install
   

3. Build the application:

   npm run build
   

Configuration

For Manual Testing

If you want to run the server manually outside of Cursor, create a .env file in the project root:

# OpenRouter Configuration (Recommended)
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENROUTER_MODEL=google/gemini-2.5-pro-exp-03-25:free
FALLBACK_OPENROUTER_MODEL=google/gemini-2.5-flash-preview:thinking

# Alternative: Google AI API Configuration
# GEMINI_API_KEY=your_google_ai_api_key
# GEMINI_MODEL=gemini-1.5-flash-latest
# FALLBACK_GEMINI_MODEL=gemini-1.5-flash-latest

# Server Configuration
UI_PORT=4999
WS_PORT=4999

# Features
AUTO_REVIEW_ON_COMPLETION=false

Running Manually

For local testing outside of Cursor:

# Using Node directly (with absolute path)
node /full/path/to/your/task-manager-mcp/dist/server.js

# Or using npm
npm start

Using with Cursor

Configuring the MCP Server

1. Create or edit Cursor's MCP configuration file:

   • Project-specific: .cursor/mcp.json in your project directory
   • Global: ~/.cursor/mcp.json in your home directory

2. Add the following to the configuration:

   {
     "mcpServers": {
       "task-manager-mcp": {
         "command": "node",
         "args": ["/full/path/to/your/task-manager-mcp/dist/server.js"],
         "env": {
           "OPENROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxxxxxx"
           // Optional configurations:
           // "OPENROUTER_MODEL": "google/gemini-2.5-pro-exp-03-25:free",
           // "FALLBACK_OPENROUTER_MODEL": "google/gemini-2.5-flash-preview:thinking",
           // "UI_PORT": "4999",
           // "WS_PORT": "4999"
         }
       }
     }
   }
   

   Replace the path and API key with your actual values.

Creating a Custom Cursor Mode

1. Go to Cursor Settings → Features → Chat → Enable Custom modes

2. Go to chat view, click the mode selector (bottom left), and select "Add custom mode"

3. Configure your mode:

   • Give it a name (e.g., "MCP Planner")
   • Choose an icon/shortcut
   • Enable tools: plan_feature, mark_task_complete, get_next_task, review_changes, adjust_plan
   • Add the following custom instructions:

   Always use plan_feature mcp tool when getting feature request before doing anything else. ALWAYS!!!!!!!! It will return the first step of the implementation. DO NOT IMPLEMENT MORE THAN WHAT THE TASK STATES. After you're done run mark_task_complete which will give you the next task. If the user says "review" use the review_changes tool. The review_changes tool will generate new tasks for you to follow, just like plan_feature. After a review, follow the same one-at-a-time task completion workflow: complete each review-generated task, mark it complete, and call get_next_task until all are done.
   
   If clarification is required at any step, you will not receive the next task and will have to run get_next_task manually after the user answers the clarification question through the UI.
   
   IMPORTANT: Your job is to complete the tasks one at a time. DO NOT DO ANY OTHER CHANGES, ONLY WHAT THE CURRENT TASK SAYS TO DO.
   

4. Save the custom mode

Using the Task Manager

1. Select your custom mode in Cursor
2. Provide a feature request (e.g., "add auth using JWT")
3. The system will:
   • Generate a step-by-step plan using Gemini
   • Open a UI in your browser showing the task list
   • Return the first task to Cursor for implementation
4. Cursor will implement only that specific task
5. The process continues with Cursor marking tasks complete and receiving the next task
6. You can say "review" to trigger a code review which may generate additional tasks

Cost Optimization

To minimize costs, consider these options:

• Use OpenRouter's free tier models (e.g., google/gemini-2.5-pro-exp-03-25:free)
• Connect your own Google AI API key to OpenRouter
• Configure fallback models carefully based on current pricing

For more information on setting up free access, see: Reddit Guide to Gemini 2.5 Pro Free Setup

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.