mcp-task-manager

Un gestor de tareas local que se conecta a Claude Desktop a través del Model Context Protocol de Anthropic. Sin interfaz de usuario, sin servicio backend: solo un proceso de Python y un archivo SQLite. Gestionas tus tareas hablando con Claude.

"Crea una tarea de alta prioridad para arreglar el error de autenticación, con fecha límite el viernes, etiquétala como backend." → tarea creada. "¿En qué debería centrarme hoy?" → devuelve tareas vencidas + urgentes + de alta prioridad. "Marca la tarea 3 como completada y muéstrame un resumen." → completada + estadísticas.

Stack: Python 3.11+ · FastMCP · SQLite · Pydantic v2 Estado: funcionando localmente, 9 herramientas implementadas

Por qué este proyecto

Creado para aprender MCP de principio a fin: ciclo de vida del servidor, registro de herramientas, transporte stdio y cómo Claude elige las herramientas a partir de solicitudes en lenguaje natural. Es un ejemplo pequeño pero completo: el tipo de cosa que ampliarías para convertirla en una herramienta interna real en el trabajo.

Cómo funciona

Los servidores MCP se ejecutan como un subproceso local. Claude Desktop se comunica con el servidor a través de stdio usando JSON-RPC. Cuando escribes un mensaje, Claude:

1. Elige qué herramienta registrada se ajusta a la solicitud

2. Rellena los parámetros a partir de tu lenguaje natural

3. Llama a la herramienta, obtiene datos estructurados (modelos Pydantic)

4. Te resume el resultado en inglés sencillo

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

Herramientas

Prioridades: low · medium · high · urgent Estados: pending · in_progress · completed · cancelled

Estructura del proyecto

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

Tres capas, una responsabilidad cada una:

• tools/ — la superficie orientada a MCP. Cada función tiene una cadena de documentación (docstring) que Claude lee para entender cuándo/cómo llamarla.

• core/repository.py — acceso a SQLite. SQL sin procesar, indexado por status, priority, due_date.

• core/models.py — validación, serialización, enumeraciones.

Configuración

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

Conectar a Claude Desktop

Abre tu configuración de Claude Desktop:

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

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

Añade el servidor:

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

Reinicia Claude Desktop. Las herramientas aparecerán bajo el icono 🔌.

Configuración

.env admite dos variables:

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

Sesión de ejemplo

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

Notas de diseño

Algunas decisiones que vale la pena mencionar, en caso de que estés leyendo esto como revisor:

• Repositorio con alcance de ciclo de vida (lifespan). El TaskRepository se construye una vez en el gestor de contexto lifespan de FastMCP y se inyecta a través de ctx.request_context.lifespan_context. Las herramientas permanecen sin estado; los detalles de conexión no se filtran al código de la herramienta.

• Enumeraciones en lugar de cadenas mágicas. Priority y TaskStatus son enumeraciones de tipo str: validadas por Pydantic en la entrada, almacenadas como cadenas en SQLite, tipadas en todo el proceso intermedio.

• Etiquetas como JSON en una columna TEXT. Pragmático para SQLite: no se necesita una tabla de unión para una herramienta local. La búsqueda utiliza LIKE sobre el JSON serializado. Si esto se trasladara a Postgres, se convertiría en un text[] o una tabla de etiquetas real.

• Indexación de las rutas críticas. status, priority, due_date: las tres columnas que utiliza cada filtro.

• plan_day elimina duplicados. Las consultas de prioridad urgente y alta pueden solaparse con la lista de vencidas, por lo que la lista de enfoque final se construye con un conjunto seen.

Limitaciones / próximos pasos

• Aún no hay pruebas: planeado pytest con un fixture de SQLite en memoria para la capa de repositorio.

• No hay tareas recurrentes.

• La búsqueda se basa en LIKE; para un conjunto de datos mayor, SQLite FTS5 sería la mejora.

• Diseñado para un solo usuario y una sola máquina. Multiusuario significaría cambiar SQLite por Postgres y añadir una columna de usuario.

Licencia

MIT