# mcp-shrimp-task-manager

> MCP Server

AI Agent Task Manager. Converts natural language to structured dev tasks with dependency tracking and iterative refinement.

## Overview

- **Category:** AI
- **Language:** TypeScript
- **Stars:** 2154
- **Forks:** 141
- **Owner:** cjo4m06
- **GitHub:** https://github.com/cjo4m06/mcp-shrimp-task-manager
- **Homepage:** https://cjo4m06.github.io/mcp-shrimp-task-manager/
- **Created:** 2025-04-12T08:59:07+00:00
- **Updated:** 2025-07-07T16:48:53+00:00
- **Source:** https://model-context-protocol.com/servers/mcp-shrimp-task-manager

## Setup

## Setup

### Prerequisites

*   **Node.js**: Ensure Node.js is installed on your system.
*   **npm**: Node Package Manager, usually bundled with Node.js.

### Installation

There are two primary methods for installing Shrimp Task Manager: via Smithery or manual installation.

#### Installing via Smithery (Recommended for Claude Desktop)

Smithery automates the installation process for Claude Desktop.

```bash
npx -y @smithery/cli install @cjo4m06/mcp-shrimp-task-manager --client claude
```

#### Manual Installation

1.  **Clone the repository (if necessary):**

    If you haven't already, clone the Shrimp Task Manager repository to your local machine.
2.  **Install dependencies:**

    Navigate to the project directory in your terminal and run:

    ```bash
    npm install
    ```

3.  **Build the project:**

    ```bash
    npm run build
    ```

### Configuration

Shrimp Task Manager requires configuration to connect to an MCP-compatible client (e.g., Cursor IDE) and to set up data storage.

#### Configuring with MCP-Compatible Clients (e.g., Cursor IDE)

Shrimp Task Manager supports global and project-specific configurations.  The recommended approach depends on whether your client supports the ListRoots protocol.

**ListRoots Protocol Support (Recommended - e.g., Cursor IDE)**

The ListRoots protocol enables automatic project isolation and flexible path configuration.

*   **Absolute Path Mode (Project Isolation):** Use a global `mcp.json` configuration. Shrimp automatically isolates projects by creating separate folders within the specified `DATA_DIR`.
*   **Relative Path Mode (Project-Contained):** Create the `DATA_DIR` within your project root directory for project-specific data storage.

**No ListRoots Protocol Support**

If your client doesn't support ListRoots, absolute paths for `DATA_DIR` are strongly recommended.

**Configuration Steps:**

1.  **Locate the MCP configuration file:**

    *   **Global Configuration (e.g., Cursor IDE: `~/.cursor/mcp.json`):**  This configuration applies to all projects.
    *   **Project-Specific Configuration:** Create a `.cursor` directory in the project root, and then create an `mcp.json` file inside it.

2.  **Add the Shrimp Task Manager configuration:**

    Add the following configuration to the `mcpServers` section of your `mcp.json` file. Choose either the Absolute Path or Relative Path option, as appropriate.

    **Option A: Absolute Path (Project Isolation - Recommended with ListRoots)**

    ```json
    {
      "mcpServers": {
        "shrimp-task-manager": {
          "command": "node",
          "args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"],
          "env": {
            "DATA_DIR": "/Users/username/ShrimpData", // Absolute path - creates project folders automatically
            "TEMPLATES_USE": "en",
            "ENABLE_GUI": "false"
          }
        }
      }
    }
    ```

    **Option B: NPX with Absolute Path (Project Isolation - Recommended with ListRoots)**

    ```json
    {
      "mcpServers": {
        "shrimp-task-manager": {
          "command": "npx",
          "args": ["-y", "mcp-shrimp-task-manager"],
          "env": {
            "DATA_DIR": "/Users/username/ShrimpData", // Absolute path - creates project folders automatically
            "TEMPLATES_USE": "en",
            "ENABLE_GUI": "false"
          }
        }
      }
    }
    ```

    **Option C: Relative Path (Project-Contained - Requires ListRoots for reliable operation)**

    ```json
    {
      "mcpServers": {
        "shrimp-task-manager": {
          "command": "node",
          "args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"],
          "env": {
            "DATA_DIR": ".shrimp", // Relative path - creates folder within project root
            "TEMPLATES_USE": "en",
            "ENABLE_GUI": "false"
          }
        }
      }
    }
    ```

    **Option D: NPX with Relative Path (Project-Contained - Requires ListRoots for reliable operation)**

    ```json
    {
      "mcpServers": {
        "shrimp-task-manager": {
          "command": "npx",
          "args": ["-y", "mcp-shrimp-task-manager"],
          "env": {
            "DATA_DIR": "shrimp-data", // Relative path - creates folder within project root
            "TEMPLATES_USE": "en",
            "ENABLE_GUI": "false"
          }
        }
      }
    }
    ```

    **Important Notes:**

    *   Replace `/path/to/mcp-shrimp-task-manager` with the actual path to your Shrimp Task Manager installation.
    *   Replace `/Users/username/ShrimpData` with your desired data directory.
    *   If using NPX, ensure `mcp-shrimp-task-manager` is globally installed or available in your project's `node_modules`.
    *   When using relative paths, the `DATA_DIR` will be created within your project directory (e.g., `./shrimp-data/`).
    *   For clients that support ListRoots, absolute paths with project isolation are recommended for ease of use and project separation.

### Environment Variables

Shrimp Task Manager uses environment variables for configuration. These can be set in your `mcp.json` file (as shown above) or in a `.env` file in the project root.

*   **`DATA_DIR`**:  The directory where Shrimp Task Manager stores task data, conversation logs, and other information.  Use an absolute path for best results, especially if your client doesn't support ListRoots.
*   **`TEMPLATES_USE`**: Specifies the template set to use for prompts. Defaults to `en` (English).  Other available option is `zh` (Traditional Chinese).  To use custom templates, copy the `src/prompts/templates_en` directory to the location specified by `DATA_DIR`, rename the copied directory (e.g., to `my_templates`), and set `TEMPLATES_USE` to the new directory name (e.g., `my_templates`).
*   **`ENABLE_GUI`**: Enables or disables the web-based graphical user interface. Set to `true` to enable, `false` to disable (default).
*   **`WEB_PORT`**: Specifies the port for the web GUI. If not specified, an available port will be automatically selected. Only takes effect when `ENABLE_GUI` is set to `true`.
*   **`MCP_PROMPT_[FUNCTION_NAME]`**:  Overrides the default prompt for a specific function.  See the [Prompt Customization Guide](docs/en/prompt-customization.md) for details.
*   **`MCP_PROMPT_[FUNCTION_NAME]_APPEND`**: Appends content to the existing prompt for a specific function. See the [Prompt Customization Guide](docs/en/prompt-customization.md) for details.

**Example `.env` file:**

```
DATA_DIR=/Users/username/ShrimpData
TEMPLATES_USE=en
ENABLE_GUI=true
WEB_PORT=3000
```

### Running the Service

After configuration, start the Shrimp Task Manager service. If using `node`, run:

```bash
node dist/index.js
```

If using NPX, the service will start automatically when you interact with it through your MCP-compatible client.

### Using the Web GUI (Optional)

If you enabled the web GUI (`ENABLE_GUI=true`), a `WebGUI.md` file will be created in your `DATA_DIR` containing the access address.  Open this address in your web browser to access the GUI.

## Tools

## Available Tools

Here's a breakdown of the available tools and features within the MCP Shrimp Task Manager:

**Features:**

*   **Task Planning and Analysis:** Deep understanding and analysis of complex task requirements.
*   **Intelligent Task Decomposition:** Automatically breaks down large tasks into manageable smaller tasks.
*   **Dependency Management:** Precisely handles dependencies between tasks, ensuring correct execution order.
*   **Execution Status Tracking:** Real-time monitoring of task execution progress and status.
*   **Task Completeness Verification:** Ensures task results meet expected requirements.
*   **Task Complexity Assessment:** Automatically evaluates task complexity and provides optimal handling suggestions.
*   **Automatic Task Summary Updates:** Automatically generates summaries upon task completion, optimizing memory performance.
*   **Task Memory Function:** Automatically backs up task history, providing long-term memory and reference capabilities.
*   **Research Mode:** Systematic technical research capabilities with guided workflows for exploring technologies, best practices, and solution comparisons.  Example usage: "Enter research mode for [your topic]", "Research [specific technology/problem]".
*   **Project Rules Initialization:** Defines project standards and rules to maintain consistency across large projects. Example usage: "init rules", "update project rules".
*   **Web GUI:** Provides an optional web-based graphical user interface for task management. Enable by setting `ENABLE_GUI=true` in your `.env` file.

**Tools:**

| Category                     | Tool Name            | Description