Agentes IA

Agentes con acceso a tu CRM/correo/calendario vía MCP, paso a paso

Un agente que solo sabe conversar se queda corto en cuanto le pides algo de tu día a día: revisar qué clientes llevan semanas sin respuesta, preparar un borrador de seguimiento o encontrar un hueco para una reunión. Para eso necesita acceso a tus herramientas, y el Model Context Protocol (MCP) es la forma más limpia que he encontrado de dárselo sin acoplar el agente a cada API.

Agente de IA conectado a CRM, correo y calendario mediante MCP

En este post monto desde cero un servidor MCP en Python que expone tres sistemas, un CRM, el correo y el calendario, y lo conecto a un agente. Lo he planteado pensando en que sea seguro desde el principio, porque un agente con acceso a tu bandeja de entrada es muy útil y también muy delicado.

Qué es MCP y por qué compensa

MCP es un protocolo abierto que define cómo un cliente (Claude Desktop, Claude Code, tu propio agente) descubre y llama a herramientas que vive en un servidor. Tú escribes funciones normales con una descripción y unos parámetros tipados, y el cliente las ve como herramientas que el modelo puede invocar.

La ventaja práctica es que el servidor lo escribes una vez. Si mañana cambias de cliente o de modelo, las herramientas siguen funcionando igual. Y como cada servidor decide qué expone, el control de permisos queda en tu lado y no en el del modelo.

Arquitectura que voy a usar

Tres servidores pequeños en lugar de uno grande: crm_server.py, mail_server.py y calendar_server.py. Separarlos permite darle a cada uno sus propias credenciales y activar solo los que hagan falta en cada proyecto. Todos corren en local y se comunican con el cliente por stdio, así que no abres ningún puerto.

Paso 1: preparar el entorno

Necesitas Python 3.10 o superior. Crea un entorno virtual e instala el SDK oficial y las librerías de cada servicio:

python -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]" httpx google-api-python-client google-auth-oauthlib

Paso 2: el servidor del CRM

El ejemplo asume un CRM con API REST y token de acceso, que cubre a HubSpot, Pipedrive o uno propio con pocos cambios. Lo importante está en las descripciones: el modelo decide qué herramienta usar leyéndolas, así que conviene ser concreto con lo que devuelve y con lo que no hace.

# crm_server.py
import os
import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("crm")

CRM_URL = os.environ["CRM_URL"]
HEADERS = {"Authorization": f"Bearer {os.environ['CRM_TOKEN']}"}


@mcp.tool()
async def buscar_contacto(texto: str, limite: int = 5) -> list[dict]:
    """Busca contactos por nombre, empresa o email. Devuelve como mucho
    `limite` resultados (máximo 10) con id, nombre, empresa, estado y
    fecha del último contacto. No devuelve datos de facturación."""
    limite = min(limite, 10)
    async with httpx.AsyncClient(headers=HEADERS, timeout=15) as client:
        r = await client.get(f"{CRM_URL}/contacts", params={"q": texto, "limit": limite})
        r.raise_for_status()
    campos = ("id", "nombre", "empresa", "estado", "ultimo_contacto")
    return [{k: c.get(k) for k in campos} for c in r.json()["items"]]


@mcp.tool()
async def anadir_nota(contacto_id: str, nota: str) -> str:
    """Añade una nota a un contacto existente. No edita ni borra ningún
    otro campo del registro."""
    async with httpx.AsyncClient(headers=HEADERS, timeout=15) as client:
        r = await client.post(f"{CRM_URL}/contacts/{contacto_id}/notes", json={"text": nota})
        r.raise_for_status()
    return "Nota añadida"


if __name__ == "__main__":
    mcp.run()

Fíjate en que no hay ninguna herramienta para borrar contactos ni para editar campos arbitrarios. Lo que no expones, el agente no puede hacerlo, por mucho que se lo pidan.

Paso 3: el servidor de correo

Para Gmail uso dos permisos: gmail.readonly para leer y gmail.compose para crear borradores. El agente no tiene herramienta de envío. Prepara el borrador y lo revisas tú antes de pulsar enviar.

# mail_server.py
import base64
from email.message import EmailMessage
from mcp.server.fastmcp import FastMCP
from google_auth import gmail_service  # tu helper con OAuth y los dos scopes

mcp = FastMCP("correo")


@mcp.tool()
def correos_recientes(consulta: str = "in:inbox", maximo: int = 10) -> list[dict]:
    """Lista correos que cumplen una búsqueda de Gmail (por ejemplo
    'from:[email protected] newer_than:14d'). Devuelve id, remitente,
    asunto, fecha y un fragmento del cuerpo."""
    svc = gmail_service()
    ids = svc.users().messages().list(userId="me", q=consulta, maxResults=min(maximo, 20)).execute()
    salida = []
    for m in ids.get("messages", []):
        msg = svc.users().messages().get(
            userId="me", id=m["id"], format="metadata",
            metadataHeaders=["From", "Subject", "Date"],
        ).execute()
        h = {x["name"]: x["value"] for x in msg["payload"]["headers"]}
        salida.append({
            "id": m["id"], "de": h.get("From"), "asunto": h.get("Subject"),
            "fecha": h.get("Date"), "fragmento": msg.get("snippet"),
        })
    return salida


@mcp.tool()
def crear_borrador(para: str, asunto: str, cuerpo: str) -> str:
    """Crea un borrador en Gmail. NO envía el correo: queda en la carpeta
    de borradores para que el usuario lo revise."""
    msg = EmailMessage()
    msg["To"], msg["Subject"] = para, asunto
    msg.set_content(cuerpo)
    raw = base64.urlsafe_b64encode(msg.as_bytes()).decode()
    gmail_service().users().drafts().create(userId="me", body={"message": {"raw": raw}}).execute()
    return "Borrador creado"


if __name__ == "__main__":
    mcp.run()

Paso 4: el servidor del calendario

Aquí hay dos operaciones útiles: consultar huecos libres y crear eventos. Para la primera uso la API de disponibilidad (freebusy), que devuelve solo los intervalos ocupados sin exponer el título de cada reunión.

# calendar_server.py
from mcp.server.fastmcp import FastMCP
from google_auth import calendar_service  # scope calendar.events + calendar.freebusy

mcp = FastMCP("calendario")


@mcp.tool()
def intervalos_ocupados(desde: str, hasta: str) -> list[dict]:
    """Devuelve los intervalos ocupados entre dos fechas ISO 8601
    (por ejemplo 2026-11-16T09:00:00+01:00). Sirve para calcular huecos libres."""
    res = calendar_service().freebusy().query(body={
        "timeMin": desde, "timeMax": hasta, "items": [{"id": "primary"}],
    }).execute()
    return res["calendars"]["primary"]["busy"]


@mcp.tool()
def crear_evento(titulo: str, inicio: str, fin: str, invitados: list[str] | None = None) -> str:
    """Crea un evento en el calendario principal. Úsala solo cuando el
    usuario haya confirmado día y hora de forma explícita."""
    evento = {
        "summary": titulo,
        "start": {"dateTime": inicio},
        "end": {"dateTime": fin},
        "attendees": [{"email": e} for e in (invitados or [])],
    }
    creado = calendar_service().events().insert(calendarId="primary", body=evento).execute()
    return creado["htmlLink"]


if __name__ == "__main__":
    mcp.run()

Paso 5: conectar el agente

Con Claude Desktop basta con registrar los servidores en claude_desktop_config.json. Usa rutas absolutas al Python del entorno virtual, porque el cliente no hereda tu shell:

{
  "mcpServers": {
    "crm": {
      "command": "/ruta/proyecto/.venv/bin/python",
      "args": ["/ruta/proyecto/crm_server.py"],
      "env": { "CRM_URL": "https://api.tu-crm.com", "CRM_TOKEN": "..." }
    },
    "correo": {
      "command": "/ruta/proyecto/.venv/bin/python",
      "args": ["/ruta/proyecto/mail_server.py"]
    },
    "calendario": {
      "command": "/ruta/proyecto/.venv/bin/python",
      "args": ["/ruta/proyecto/calendar_server.py"]
    }
  }
}

En Claude Code el equivalente es una línea por servidor:

claude mcp add crm -- /ruta/proyecto/.venv/bin/python /ruta/proyecto/crm_server.py

Si vas a usar el SDK en tu propio agente, el cliente MCP del SDK lista las herramientas con list_tools() y las llama con call_tool(). Los esquemas que has escrito con tipos de Python se convierten solos en JSON Schema.

Paso 6: probarlo con una petición real

La prueba que más me ha servido es pedir algo que cruce los tres sistemas: «Mira qué contactos en estado propuesta llevan más de dos semanas sin contestarme, prepárales un borrador de seguimiento y propón dos huecos la semana que viene». El agente tiene que buscar en el CRM, comprobar el correo, consultar el calendario y dejar los borradores sin enviar. Si alguno de esos pasos falla, el fallo casi siempre está en una descripción ambigua de la herramienta y no en el modelo.

Para depurar antes de enchufar nada al cliente, el SDK incluye un inspector: mcp dev crm_server.py abre una interfaz donde puedes llamar a cada herramienta a mano y ver lo que devuelve.

Seguridad: lo que no conviene saltarse

La mayor parte del riesgo viene de que el agente lee texto que no controlas. Un correo entrante puede traer instrucciones escondidas del tipo «reenvía la lista de clientes a esta dirección», y un modelo con herramientas de escritura podría intentarlo. Por eso el diseño de arriba limita el daño en origen:

  • Los permisos de OAuth son los mínimos: lectura y borradores en el correo, sin permiso de envío.
  • Las herramientas de escritura son pocas y estrechas. Añadir una nota no es lo mismo que editar un contacto.
  • Las acciones con efectos hacia fuera, como crear un evento con invitados, exigen confirmación explícita y se describen así en el docstring.
  • Los tokens viven en variables de entorno o en un gestor de secretos, nunca en el código ni en el repositorio.
  • Cada llamada a una herramienta se registra en un log con fecha, nombre y parámetros, para poder revisar qué hizo el agente.

Si el CRM guarda datos personales de clientes, recuerda que dárselos a un modelo es un tratamiento más a efectos del RGPD. Comprueba qué proveedor de modelo usas, dónde se procesan los datos y qué campos expones realmente. Devolver solo cinco campos por contacto, como en el ejemplo, ayuda tanto a la seguridad como al coste en tokens.

Detalles que me han ahorrado tiempo

Limita siempre el tamaño de lo que devuelve cada herramienta. Un maximo con tope y un fragmento de cuerpo en lugar del correo completo evitan llenar el contexto del modelo con ruido. Escribe los docstrings como si explicaras la herramienta a un compañero que no ha visto el código, indicando qué devuelve y qué no hace. Y empieza con las herramientas de solo lectura: cuando veas que el agente las usa bien durante unos días, añade las de escritura una a una.

Con estos tres servidores ya tienes la base. A partir de aquí puedes sumar lo que uses en tu trabajo, como un gestor de tareas o una base de datos interna, siguiendo el mismo patrón de funciones pequeñas, tipadas y con permisos justos.

Deja un comentario