Cómo conectar Aymakan a Gemini vía MCP

💡 ¿Sin instalación? Usa cloud.anythingmcp.com directamente. Inicia sesión, pulsa Connectors → Aymakan, pega tus credenciales, genera una MCP API key y listo. Sin Docker, sin git clone, sin servidor local.

Aymakan + Gemini

La mensajería Aymakan (Arabia Saudí) desde un agente de IA: sigue envíos por número de seguimiento o referencia de pedido, lista tus envíos, enlaces a etiquetas AWB, solicitudes de recogida y franjas horarias, ciudades, puntos PUDO, almacenes y direcciones guardadas. Crear y cancelar envíos y recogidas está incluido, desactivado al instalar.

Requisitos previos

Las instrucciones de configuración completas están incluidas en el conector (visibles en el store al seleccionarlo). Las variables de entorno requeridas:

AYMAKAN_API_KEY

Paso 1 — Obtener credenciales

La configuración lleva unos 2 minutos. Necesitas una cuenta de cliente de Aymakan, la mensajería saudí.

1. Inicia sesión en el panel de clientes de Aymakan.
2. Abre Technical → AyMakan API y copia la clave de API (el security code).
3. Pégala tal cual en AYMAKAN_API_KEY, sin la palabra Bearer.
4. Instala el conector y ejecuta aymakan_ping: logged_in debe indicar Yes.

Usa la clave de producción: una clave del entorno de desarrollo de Aymakan responde aquí Invalid Credentials. Si regeneras la clave en el panel, la anterior deja de funcionar, así que actualiza también las demás integraciones que la usen.

Qué lee: tus envíos por número de seguimiento o por tu propia referencia de pedido, con datos de entrega y de recogida, importe contra reembolso, peso, bultos, estado actual y todo el historial de estados en inglés y en árabe; la lista de todos los envíos de tu cuenta con los intentos de entrega y las fechas principales; los enlaces a las etiquetas (AWB); tus solicitudes de recogida, las ciudades donde se puede recoger y las franjas libres de una fecha; las ciudades a las que entrega Aymakan; puntos PUDO como taquillas y tiendas asociadas; los almacenes de Aymakan; y las direcciones de recogida guardadas en tu cuenta.

Etiquetas solo antes de la recogida: Aymakan devuelve el enlace al PDF de la etiqueta solo mientras el envío sigue en estado AY-0001 (creado, aún sin recoger). Después de la recogida la API responde 422, así que imprime tus etiquetas antes de que pase el mensajero. Para varios envíos, la IA puede traer un único PDF con todas las etiquetas.

Búsqueda por tu número de pedido: solo funciona con envíos creados con una referencia, y solo encuentra envíos de tu propia cuenta. Una referencia que no existe responde No Shipments Found.

Desactivadas al instalar: aymakan_create_shipment, aymakan_cancel_shipment, aymakan_create_pickup_request y aymakan_cancel_pickup_request. Reservan o cancelan trabajo real del mensajero, por eso un administrador las activa de forma deliberada. Aun así, la IA te muestra primero el envío (destinatario, ciudad, importe contra reembolso, bultos), el número de seguimiento o la solicitud de recogida, y espera tu sí. Un envío solo se puede cancelar en estado AY-0001, y una solicitud de recogida solo mientras está pendiente o en proceso.

Límites: la lista de envíos llega en páginas fijas de 100 (unos 110 KB cada una), así que para un solo envío la IA usa el seguimiento. Aymakan limita el número de solicitudes de recogida por cliente y día.

Errores habituales: 401 Invalid Credentials significa clave incorrecta, clave antigua tras regenerarla o clave de desarrollo. 422 indica el motivo en el mensaje, por ejemplo No Shipments Found, un error de validación por campo o una etiqueta pedida para un envío que ya ha pasado de AY-0001.

El conector no gestiona liquidaciones de contra reembolso ni facturas, y no reserva ni cancela envíos o recogidas mientras un administrador no active esas herramientas.

Paso 2 — Instalar el adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Paso 3 — Añadir el conector en Gemini

La URL de tu servidor: en AnythingMCP abre MCP Servers → el servidor donde está este conector y copia su URL (https://cloud.anythingmcp.com/mcp/…). Úsala donde esta guía muestra YOUR_SERVER_ID.

Gemini CLI lee los servidores MCP de ~/.gemini/settings.json (en Windows, %USERPROFILE%\.gemini\settings.json). Añade:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una clave de API MCP en AnythingMCP en MCP Servers → tu servidor → API keys y pégala en lugar de YOUR_MCP_API_KEY.
2. Guarda el archivo y reinicia gemini.
3. Ejecuta /mcp dentro de Gemini CLI (o gemini mcp list en tu terminal): anythingmcp debería aparecer como conectado.
4. Empieza a escribir prompts: Gemini CLI ya puede llamar a las herramientas de Aymakan.

Herramientas disponibles

Ejemplos de prompts

• "¿Dónde están ahora los envíos AY2866494373 y AY2866494374?"
• "Busca el envío de nuestra referencia de pedido 10045 y enséñame todo su historial de estados."
• "¿Qué envíos míos de esta semana necesitaron más de un intento de entrega, y en qué ciudades?"
• "Dame un solo PDF con las etiquetas de todos los envíos creados hoy que aún no se han recogido."
• "¿Qué franjas de recogida quedan libres mañana y qué solicitudes de recogida mías siguen pendientes?"

FAQ

¿Dónde busca Gemini CLI los servidores MCP? En ~/.gemini/settings.json para tu usuario, o en .gemini/settings.json dentro de un proyecto. gemini mcp list muestra cada servidor y si se conecta.

Siguientes pasos

• Página del conector
• Conectar a Claude
• Conectar a ChatGPT