Personal Task Manager

A Model Context Protocol (MCP) server that turns any AI assistant into a powerful task management system. Built with Python and SQLite, it exposes 19 tools for full lifecycle task management from quick to-dos to multi project workflows with priorities, tags, subtasks, and more.

AI Assistant  <-->  MCP Protocol (stdio)  <-->  Task Manager Server  <-->  SQLite DB

---

Features

Feature	Description
Due Dates & Deadlines	Set, update, or clear deadlines on any task
Priorities	Classify tasks as high, medium, or low
Status Workflow	Full lifecycle: todo > in_progress > blocked > done > archived
Tags & Labels	Flexible many-to-many tagging (e.g. @work, @home, urgent)
Notes & Descriptions	Rich markdown notes attached to any task
Subtasks & Checklists	Break tasks into ordered, toggleable checklist items
Lists & Projects	Organize tasks by context — work, personal, side-project

---

All 19 MCP Tools

Core CRUD

Tool	Signature	Description
get_schema	()	Get the full database schema
run_select_query	(query)	Run a read-only SQL SELECT query
add_task	(title, description?, due_date?, priority?, list_id?, notes?)	Create a new task
update_task	(task_id, title?, description?, status?, due_date?, priority?, list_id?, notes?)	Update any task field
delete_task	(task_id)	Delete a task and its subtasks/tags

Due Dates

Tool	Signature	Description
set_due_date	(task_id, due_date)	Set or clear a deadline (YYYY-MM-DD)

Priorities

Tool	Signature	Description
set_priority	(task_id, level)	Set priority: high / medium / low

Status Workflow

Tool	Signature	Description
set_status	(task_id, status)	Set status: todo / in_progress / blocked / done / archived

Tags & Labels

Tool	Signature	Description
add_tag	(task_id, tag)	Add a tag to a task (creates if new)
remove_tag	(task_id, tag)	Remove a tag from a task
list_by_tag	(tag)	List all tasks with a given tag

Notes

Tool	Signature	Description
update_notes	(task_id, markdown_text)	Set/replace markdown notes on a task

Subtasks & Checklists

Tool	Signature	Description
add_subtask	(parent_id, title)	Add a checklist item to a task
toggle_subtask	(subtask_id)	Toggle completion (done / not done)
delete_subtask	(subtask_id)	Remove a subtask
list_subtasks	(parent_id)	List all subtasks of a task

Lists & Projects

Tool	Signature	Description
create_list	(name, description?)	Create a new list/project
delete_list	(list_id)	Delete a list (tasks become unassigned)
move_task_to_list	(task_id, list_id)	Move a task to a list (use 0 to unassign)
list_tasks_in_list	(list_id)	List all tasks in a list

---

Quick Start

Prerequisites

• Python 3.10+
• An MCP-compatible client (e.g. Claude Desktop, Cursor, VS Code + Copilot)

Installation

# Clone the repository
git clone https://github.com/arghyapolley/personal-task-manager-mcp.git
cd personal-task-manager-mcp

# Install dependencies
pip install -r requirements.txt

Run the Server

python server.py

The server communicates via stdio using the MCP protocol. It automatically creates/migrates the tasks.db SQLite database on startup.

Connect to Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "task-manager": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Then restart Claude Desktop. You can now say things like:

"Add a high-priority task called 'Deploy v2' to my Work project, due May 10th"

"Show me all tasks tagged @urgent"

"Add subtasks to task 3: write tests, update docs, deploy"

"What's overdue?"

---

Database Schema

+---------------+       +---------------+
|    lists      |       |     tags      |
+---------------+       +---------------+
| id (PK)       |       | id (PK)       |
| name (UQ)     |       | name (UQ)     |
| description   |       +-------+-------+
| created_at    |               |
+-------+-------+               |
        |                +------+------+
        | 1:N            | task_tags   |
        |                +-------------+
+-------+-------+       | task_id(FK) |--+
|    tasks      |       | tag_id(FK)  |  |
+---------------+       +-------------+  |
| id (PK)       |<-----------------------+
| title         |
| description   |       +-------------+
| status        |       |  subtasks   |
| due_date      |       +-------------+
| priority      |  1:N  | id (PK)     |
| list_id (FK)  |<------| parent_id   |
| notes         |       | title       |
| created_at    |       |is_completed |
| updated_at    |       | sort_order  |
+---------------+       | created_at  |
                        +-------------+

---

Testing

Run the full test suite (63 tests, uses a temporary DB):

python test_server.py

  Results:  63 passed,  0 failed

Tests cover: schema creation, CRUD, priorities, status workflow, tags (add/remove/list/duplicates), notes, subtasks (add/toggle/delete/ordering), lists (create/move/unassign/delete), cascade deletes, and SQL injection guards.

---

Project Structure

personal-task-manager-mcp/
|-- server.py          # MCP server -- 19 tools, DB init, schema migration
|-- test_server.py     # Comprehensive test suite (63 assertions)
|-- requirements.txt   # Python dependencies (mcp, pydantic)
|-- tasks.db           # SQLite database (auto-created on first run)
+-- README.md          # This file

---