mcp-task-manager

A local task manager that plugs into Claude Desktop through Anthropic's Model Context Protocol. No UI, no backend service — just a Python process and a SQLite file. You manage tasks by talking to Claude.

"Create a high-priority task to fix the auth bug, due Friday, tag it backend." → task created. "What should I focus on today?" → returns overdue + urgent + high-priority tasks. "Mark task 3 completed and show me a summary." → done + stats.

Stack: Python 3.11+ · FastMCP · SQLite · Pydantic v2 Status: working locally, 9 tools implemented

---

Why this project

Built to learn MCP end-to-end: server lifecycle, tool registration, stdio transport, and how Claude picks tools from natural-language requests. It's a small but complete example — the kind of thing you'd extend into a real internal tool at work.

---

How it works

MCP servers run as a local subprocess. Claude Desktop talks to the server over stdio using JSON-RPC. When you type a message, Claude:

1. Picks which registered tool fits the request
2. Fills in the parameters from your natural language
3. Calls the tool, gets back structured data (Pydantic models)
4. Summarises the result back to you in plain English

Claude Desktop  ──── JSON-RPC (stdio) ────  server.py  (FastMCP)
                                                │
                                         TaskRepository
                                                │
                                           tasks.db  (SQLite)

---

Tools

Tool	What it does
create_task	Create a task with title, description, priority, due date, tags
list_tasks	List tasks, optionally filtered by status and/or priority
get_task	Fetch a single task by ID
update_task	Update any field (title, description, priority, status, due date, tags)
complete_task	Shortcut — mark as completed
delete_task	Delete a task by ID
search_tasks	Substring search across title, description, and tags
get_summary	Counts by status and priority + overdue count
plan_day	Prioritised focus list for today (overdue + urgent + high)

Priorities: low · medium · high · urgent Statuses: pending · in_progress · completed · cancelled

---

Project structure

mcp-task-manager/
├── server.py           # FastMCP entry point, tool registration, lifespan
├── core/
│   ├── models.py       # Pydantic models + enums (Task, TaskCreate, TaskUpdate, TaskSummary)
│   └── repository.py   # SQLite DAO — CRUD, search, summary
├── tools/
│   └── __init__.py     # 9 MCP tool functions (thin layer over repository)
├── pyproject.toml
└── .env.example

Three layers, one responsibility each:

• tools/ — the MCP-facing surface. Each function has a docstring that Claude reads to understand when/how to call it.
• core/repository.py — SQLite access. Raw SQL, indexed on status, priority, due_date.
• core/models.py — validation, serialization, enums.

---

Setup

Requirements: Python 3.11+, Claude Desktop.

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

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e .
cp .env.example .env

Connect to Claude Desktop

Open your Claude Desktop config:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json

Add the server:

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

Restart Claude Desktop. The tools will show up under the 🔌 icon.

Configuration

.env supports two variables:

DATABASE_PATH=tasks.db       # where SQLite stores data
SERVER_NAME=mcp-task-manager # name shown in Claude Desktop

---

Example session

You:    Add a task: refactor the auth filter, high priority, due tomorrow, tags: backend, security

Claude: Created task #1 — "Refactor the auth filter" (high, due 2025-04-19, tags: backend, security)

You:    What's my plan for today?

Claude: 📅 Day plan for 2025-04-18
        🔥 FOCUS (urgent + high priority)
          [1] [HIGH] Refactor the auth filter  #backend #security
        📊 Total: 1 | In progress: 0 | Overdue: 0

You:    Mark it in progress and show a summary

Claude: Task #1 updated — status: in_progress.
        📊 Total: 1 | Pending: 0 | In progress: 1 | Completed: 0 | Overdue: 0

---

Design notes

A few choices worth calling out, in case you're reading this as a reviewer:

• Lifespan-scoped repository. The TaskRepository is built once in FastMCP's lifespan context manager and injected via ctx.request_context.lifespan_context. Tools stay stateless; the connection details don't leak into tool code.
• Enums instead of magic strings. Priority and TaskStatus are str enums — validated by Pydantic on input, stored as strings in SQLite, typed everywhere in between.
• Tags as JSON in a TEXT column. Pragmatic for SQLite — no junction table needed for a local tool. Search uses LIKE over the serialized JSON. If this ever moved to Postgres, it'd become a text[] or a real tags table.
• Indexed the hot paths. status, priority, due_date — the three columns every filter hits.
• plan_day deduplicates. Urgent and high-priority queries can overlap with the overdue list, so the final focus list is built with a seen set.

---

Limitations / next steps

• No tests yet — planned: pytest with an in-memory SQLite fixture for the repository layer.
• No recurring tasks.
• Search is LIKE-based; for a bigger dataset, SQLite FTS5 would be the upgrade.
• Single-user, single-machine by design. Multi-user would mean swapping SQLite for Postgres and adding a user column.

---

License

MIT