What is Mcp Task Manager Server

The mcp-task-manager-server is a local Model Context Protocol (MCP) server that provides backend tools for client-driven project and task management using a SQLite database.

Use cases

Use cases include managing software development tasks, organizing research projects, coordinating team activities, and facilitating AI-driven task management workflows.

How to use

To use the mcp-task-manager-server, set up the server locally and connect your MCP clients (like AI agents or scripts) to it. Utilize the provided tools to create projects, manage tasks, and interact with the SQLite database for data persistence.

Key features

Key features include project-based organization of tasks, SQLite persistence for data storage, client-driven interaction without dictating workflow, compliance with the Model Context Protocol, comprehensive task management capabilities, and import/export functionality for project data in JSON format.

Where to use

The mcp-task-manager-server is suitable for use in software development, project management, AI task management, and any scenario where structured task data needs to be managed within distinct projects.

MCP Task Manager Server

A local Model Context Protocol (MCP) server providing backend tools for client-driven project and task management using a SQLite database.

Overview

This server acts as a persistent backend for local MCP clients (like AI agents or scripts) that need to manage structured task data within distinct projects. It handles data storage and provides a standardized set of tools for interaction, while the strategic workflow logic resides within the client.

Key Features:

• Project-Based: Tasks are organized within distinct projects.
• SQLite Persistence: Uses a local SQLite file (./data/taskmanager.db by default) for simple, self-contained data storage.
• Client-Driven: Provides tools for clients; does not dictate workflow.
• MCP Compliant: Adheres to the Model Context Protocol for tool definition and communication.
• Task Management: Supports creating projects, adding tasks, listing/showing tasks, updating status, expanding tasks into subtasks, and identifying the next actionable task.
• Import/Export: Allows exporting project data to JSON and importing from JSON to create new projects.

Implemented MCP Tools

The following tools are available for MCP clients:

• createProject:
  • Description: Creates a new, empty project.
  • Params: projectName (string, optional, max 255)
  • Returns: { project_id: string }
• addTask:
  • Description: Adds a new task to a project.
  • Params: project_id (string, required, UUID), description (string, required, 1-1024), dependencies (string[], optional, max 50), priority (enum ‘high’|‘medium’|‘low’, optional, default ‘medium’), status (enum ‘todo’|‘in-progress’|‘review’|‘done’, optional, default ‘todo’)
  • Returns: Full TaskData object of the created task.
• listTasks:
  • Description: Lists tasks for a project, with optional filtering and subtask inclusion.
  • Params: project_id (string, required, UUID), status (enum ‘todo’|‘in-progress’|‘review’|‘done’, optional), include_subtasks (boolean, optional, default false)
  • Returns: Array of TaskData or StructuredTaskData objects.
• showTask:
  • Description: Retrieves full details for a specific task, including dependencies and direct subtasks.
  • Params: project_id (string, required, UUID), task_id (string, required)
  • Returns: FullTaskData object.
• setTaskStatus:
  • Description: Updates the status of one or more tasks.
  • Params: project_id (string, required, UUID), task_ids (string[], required, 1-100), status (enum ‘todo’|‘in-progress’|‘review’|‘done’, required)
  • Returns: { success: true, updated_count: number }
• expandTask:
  • Description: Breaks a parent task into subtasks, optionally replacing existing ones.
  • Params: project_id (string, required, UUID), task_id (string, required), subtask_descriptions (string[], required, 1-20, each 1-512), force (boolean, optional, default false)
  • Returns: Updated parent FullTaskData object including new subtasks.
• getNextTask:
  • Description: Identifies the next actionable task based on status (‘todo’), dependencies (‘done’), priority, and creation date.
  • Params: project_id (string, required, UUID)
  • Returns: FullTaskData object of the next task, or null if none are ready.
• exportProject:
  • Description: Exports complete project data as a JSON string.
  • Params: project_id (string, required, UUID), format (enum ‘json’, optional, default ‘json’)
  • Returns: JSON string representing the project.
• importProject:
  • Description: Creates a new project from an exported JSON string.
  • Params: project_data (string, required, JSON), new_project_name (string, optional, max 255)
  • Returns: { project_id: string } of the newly created project.
• updateTask:
  • Description: Updates specific details (description, priority, dependencies) of an existing task.
  • Params: project_id (string, required, UUID), task_id (string, required, UUID), description (string, optional, 1-1024), priority (enum ‘high’|‘medium’|‘low’, optional), dependencies (string[], optional, max 50, replaces existing)
  • Returns: Updated FullTaskData object.
• deleteTask:
  • Description: Deletes one or more tasks (and their subtasks/dependency links via cascade).
  • Params: project_id (string, required, UUID), task_ids (string[], required, 1-100)
  • Returns: { success: true, deleted_count: number }
• deleteProject:
  • Description: Permanently deletes a project and ALL associated data. Use with caution!
  • Params: project_id (string, required, UUID)
  • Returns: { success: true }

(Note: Refer to the corresponding src/tools/*Params.ts files for detailed Zod schemas and parameter descriptions.)

Getting Started

1. Prerequisites: Node.js (LTS recommended), npm.

2. Install Dependencies:

   npm install
   

3. Run in Development Mode: (Uses ts-node and nodemon for auto-reloading)

   npm run dev
   

   The server will connect via stdio. Logs (JSON format) will be printed to stderr. The SQLite database will be created/updated in ./data/taskmanager.db.

4. Build for Production:

   npm run build
   

5. Run Production Build:

   npm start
   

Configuration

• Database Path: The location of the SQLite database file can be overridden by setting the DATABASE_PATH environment variable. The default is ./data/taskmanager.db.
• Log Level: The logging level can be set using the LOG_LEVEL environment variable (e.g., debug, info, warn, error). The default is info.

Project Structure

• /src: Source code.
  • /config: Configuration management.
  • /db: Database manager and schema (schema.sql).
  • /repositories: Data access layer (SQLite interaction).
  • /services: Core business logic.
  • /tools: MCP tool definitions (*Params.ts) and implementation (*Tool.ts).
  • /types: Shared TypeScript interfaces (currently minimal, mostly in repos/services).
  • /utils: Logging, custom errors, etc.
  • createServer.ts: Server instance creation.
  • server.ts: Main application entry point.
• /dist: Compiled JavaScript output.
• /docs: Project documentation (PRD, Feature Specs, RFC).
• /data: Default location for the SQLite database file (created automatically).
• tasks.md: Manual task tracking file for development.
• Config files (package.json, tsconfig.json, .eslintrc.json, etc.)

Linting and Formatting

• Lint: npm run lint
• Format: npm run format

(Code is automatically linted/formatted on commit via Husky/lint-staged).