Aprende FastMCP - Ejemplos de Servidores MCP

Un proyecto de aprendizaje que demuestra cómo construir servidores Model Context Protocol (MCP) usando FastMCP, un framework de Python para crear herramientas y recursos compatibles con MCP.

Acerca de Este Proyecto

Este repositorio contiene dos implementaciones completas de servidores MCP:

• Servidor Demo - Ejemplos sencillos para aprender los conceptos básicos de FastMCP

• Registro de Gastos - Una aplicación completa del mundo real

Perfecto para entender cómo construir servidores MCP que pueden usarse con Claude, otros modelos de IA o aplicaciones personalizadas.

Related MCP server: expense-tracker-mcp-server

📋 Servidor 1: Demo (main.py)

Un servidor MCP básico con herramientas simples.

Herramientas

roll_dice(n_dice: int) -> list[int]

Lanza n dados de seis caras y devuelve los resultados.

roll_dice(3) → [4, 2, 6]

add_numbers(a: float, b: float) -> float

Suma dos números y devuelve el resultado.

add_numbers(5, 3) → 8

Ejecutar el Servidor Demo

python main.py

💰 Servidor 2: Registro de Gastos (test.py)

Un servidor MCP completo de gestión de gastos con persistencia en base de datos, categorización y filtros avanzados.

Características

• Base de datos SQLite para almacenamiento persistente

• Sistema de categorías jerárquico (categoría principal + subcategoría)

• Filtrado por rango de fechas

• Resumen de gastos por categoría

• Operaciones CRUD (Crear, Leer, Actualizar, Eliminar)

• Fusión/renombrado de categorías

Estructura de Datos

Cada entrada de gasto contiene:

• id - Identificador único (auto-incremental)

• date - Fecha del gasto (formato de cadena)

• amount - Monto del gasto en valor numérico

• category - Categoría principal (de categories.json)

• subcategory - Subcategoría opcional para seguimiento detallado

• note - Descripción o nota opcional

Categorías Disponibles

El registro de gastos soporta 12 categorías principales con múltiples subcategorías cada una:

• Food - comestibles, restaurantes, café, etc.

• Transport - combustible, transporte público, taxi/ride-hailing, estacionamiento, peajes

• Housing - alquiler, mantenimiento, impuesto predial, reparaciones, mobiliario

• Utilities - electricidad, agua, gas, internet, móvil, TV

• Health - medicamentos, consulta médica, diagnósticos, gimnasio

• Education - libros, cursos, suscripciones en línea, tasas de examen

• Family & Kids - cuotas escolares, guardería, juguetes, eventos

• Entertainment - películas, suscripciones de streaming, juegos, salidas

• Shopping - ropa, calzado, electrónica, electrodomésticos, decoración del hogar

• Subscriptions - herramientas SaaS, cloud/IA, música, almacenamiento, boletines

• Personal Care - salón, cuidado personal, cosméticos, higiene

• Gifts & Donations - regalos personales, donaciones benéficas, regalos festivos

• Finance & Fees - comisiones bancarias, comisiones de inversión, etc.

Herramientas

add_expense(date: str, amount: int, category: str, subcategory: str = "", note: str = "")

Añade una nueva entrada de gasto a la base de datos.

{
  "date": "2026-08-20",
  "amount": 45,
  "category": "food",
  "subcategory": "dining_out",
  "note": "Lunch with friends"
}

Devuelve: {"status": "ok", "id": 1}

list_expenses(start_date: str, end_date: str)

Lista todos los gastos dentro de un rango de fechas inclusivo (formato AAAA-MM-DD).

list_expenses("2026-08-01", "2026-08-31")

Devuelve un array de registros de gastos con todos los campos.

summarize(start_date: str, end_date: str, category: str = None)

Obtiene el monto total gastado por categoría dentro de un rango de fechas. Opcionalmente filtra por una categoría específica.

summarize("2026-08-01", "2026-08-31")
summarize("2026-08-01", "2026-08-31", "food")

Devuelve:

[
  {"category": "food", "total_amount": 150},
  {"category": "transport", "total_amount": 50}
]

update_expense(id: int, date: str = None, amount: float = None, category: str = None, subcategory: str = None, note: str = None)

Actualiza campos específicos de un gasto existente. Solo se modifican los campos proporcionados.

update_expense(1, amount=50, note="Updated note")

Devuelve: {"status": "ok", "id": 1, "updated_fields": {...}}

delete_expense(id: int)

Elimina una entrada de gasto por su id.

delete_expense(1)

Devuelve: {"status": "ok", "deleted_id": 1}

merge_categories(old_categories: list[str], new_category: str)

Renombra o fusiona una o más etiquetas de categoría en una sola categoría nueva. Útil para consolidar categorías de gastos.

merge_categories(["food", "dining"], "meals")

Devuelve: {"status": "ok", "rows_updated": 15, "new_category": "meals"}

Recursos

expense://categories

Devuelve la estructura de categorías como JSON. Este recurso se lee en cada consulta, por lo que puedes editar categories.json sin reiniciar el servidor.

Ejecutar el Registro de Gastos

python test.py

Base de datos: Crea expenses.db en el mismo directorio para almacenamiento persistente.

Instalación y Configuración

Requisitos Previos

• Python 3.14+

• FastMCP 3.4.7+

Instalar Dependencias

pip install fastmcp>=3.4.7

O usando el archivo pyproject.toml del proyecto:

pip install -e .

Estructura del Proyecto

learn-fastmcp/
├── main.py              # Demo server (roll_dice, add_numbers)
├── test.py              # Expense Tracker server (full MCP implementation)
├── categories.json      # Category definitions for expense tracker
├── expenses.db          # SQLite database (auto-created by test.py)
├── pyproject.toml       # Project configuration
└── README.md            # This file

Ruta de Aprendizaje

1. Empieza con main.py para entender los conceptos básicos:

   • Cómo crear una instancia de FastMCP

   • Cómo definir herramientas simples con el decorador @mcp.tool

   • Cómo ejecutar el servidor con mcp.run()

2. Continúa con test.py para aprender patrones avanzados:

   • Integración con base de datos SQLite

   • Entrada/salida de archivos y gestión de recursos

   • Lógica compleja de herramientas (operaciones CRUD)

   • Recursos con el decorador @mcp.resource

   • Parámetros opcionales y condicionales

   • Manejo de errores y validación

Conceptos Clave de FastMCP

Herramientas

Funciones decoradas con @mcp.tool() que pueden ser llamadas por clientes MCP. Cada herramienta tiene:

• Parámetros de entrada con anotaciones de tipo

• Un docstring que describe su funcionalidad

• Un valor de retorno

Recursos

Contenido estático o dinámico accesible mediante URI. Definidos con @mcp.resource():

• Identificados por una URI única (por ejemplo, expense://categories)

• Opcionalmente especifican el tipo MIME

• Pueden leer archivos o calcular contenido dinámicamente

Ciclo de Vida del Servidor

mcp = FastMCP("ServerName")  # Create instance

@mcp.tool()                  # Define tools
def my_tool(): ...

if __name__ == "__main__":
    mcp.run()               # Start the server

Próximos Pasos

• Modifica el servidor demo para añadir nuevas herramientas

• Amplía el registro de gastos con nuevas funciones (por ejemplo, presupuestos, gastos recurrentes)

• Crea tu propio servidor MCP para un dominio que te interese

• Conecta tu servidor MCP a Claude usando el protocolo MCP

Recursos

• Documentación de MCP

• FastMCP en GitHub

• Documentación de Tipos en Python

¡Feliz aprendizaje! 🚀