mcp-task-manager

Ein lokaler Aufgabenmanager, der über das Model Context Protocol von Anthropic in Claude Desktop eingebunden wird. Keine Benutzeroberfläche, kein Backend-Dienst — nur ein Python-Prozess und eine SQLite-Datei. Sie verwalten Aufgaben, indem Sie mit Claude sprechen.

„Erstelle eine Aufgabe mit hoher Priorität, um den Auth-Bug zu beheben, fällig am Freitag, markiere sie als Backend.“ → Aufgabe erstellt. „Worauf sollte ich mich heute konzentrieren?“ → gibt überfällige + dringende + Aufgaben mit hoher Priorität zurück. „Markiere Aufgabe 3 als erledigt und zeige mir eine Zusammenfassung.“ → erledigt + Statistiken.

Stack: Python 3.11+ · FastMCP · SQLite · Pydantic v2 Status: lokal funktionsfähig, 9 Tools implementiert

Warum dieses Projekt

Entwickelt, um MCP von Grund auf zu lernen: Server-Lebenszyklus, Tool-Registrierung, stdio-Transport und wie Claude Tools aus natürlichsprachlichen Anfragen auswählt. Es ist ein kleines, aber vollständiges Beispiel — die Art von Projekt, die man bei der Arbeit zu einem echten internen Tool erweitern würde.

Funktionsweise

MCP-Server laufen als lokaler Subprozess. Claude Desktop kommuniziert mit dem Server über stdio mittels JSON-RPC. Wenn Sie eine Nachricht eingeben, passiert Folgendes:

1. Claude wählt aus, welches registrierte Tool zur Anfrage passt

2. Füllt die Parameter aus Ihrer natürlichen Sprache aus

3. Ruft das Tool auf und erhält strukturierte Daten zurück (Pydantic-Modelle)

4. Fasst das Ergebnis für Sie in einfachem Englisch zusammen

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

Tools

Prioritäten: low · medium · high · urgent Status: pending · in_progress · completed · cancelled

Projektstruktur

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

Drei Ebenen, jede mit einer eigenen Verantwortung:

• tools/ — die MCP-Schnittstelle. Jede Funktion hat einen Docstring, den Claude liest, um zu verstehen, wann und wie sie aufgerufen werden soll.

• core/repository.py — SQLite-Zugriff. Rohes SQL, indiziert nach status, priority, due_date.

• core/models.py — Validierung, Serialisierung, Enums.

Einrichtung

Anforderungen: 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

Verbindung zu Claude Desktop herstellen

Öffnen Sie Ihre Claude Desktop-Konfiguration:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

Fügen Sie den Server hinzu:

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

Starten Sie Claude Desktop neu. Die Tools erscheinen unter dem 🔌-Symbol.

Konfiguration

.env unterstützt zwei Variablen:

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

Beispiel-Sitzung

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-Hinweise

Ein paar Entscheidungen, die erwähnenswert sind, falls Sie dies als Reviewer lesen:

• Lifespan-scoped Repository. Das TaskRepository wird einmal im lifespan-Kontextmanager von FastMCP erstellt und über ctx.request_context.lifespan_context injiziert. Tools bleiben zustandslos; die Verbindungsdetails gelangen nicht in den Tool-Code.

• Enums statt magischer Strings. Priority und TaskStatus sind str-Enums — validiert durch Pydantic bei der Eingabe, gespeichert als Strings in SQLite, überall dazwischen typisiert.

• Tags als JSON in einer TEXT-Spalte. Pragmatisch für SQLite — keine Verknüpfungstabelle für ein lokales Tool erforderlich. Die Suche verwendet LIKE über das serialisierte JSON. Sollte dies jemals zu Postgres migriert werden, würde es zu einem text[] oder einer echten Tag-Tabelle werden.

• Indizierung der Hot-Paths. status, priority, due_date — die drei Spalten, die bei jedem Filter abgefragt werden.

• plan_day dedupliziert. Abfragen für dringende Aufgaben und Aufgaben mit hoher Priorität können sich mit der Liste der überfälligen Aufgaben überschneiden, daher wird die endgültige Fokusliste mit einem seen-Set erstellt.

Einschränkungen / nächste Schritte

• Noch keine Tests — geplant: pytest mit einem In-Memory-SQLite-Fixture für die Repository-Ebene.

• Keine wiederkehrenden Aufgaben.

• Die Suche basiert auf LIKE; für einen größeren Datensatz wäre SQLite FTS5 das Upgrade.

• Design für einen einzelnen Benutzer auf einem einzelnen Rechner. Mehrbenutzerfähigkeit würde bedeuten, SQLite gegen Postgres auszutauschen und eine Benutzer-Spalte hinzuzufügen.

Lizenz

MIT