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.

Related MCP server: Tasks MCP Server

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