Semilla MCP Server

Servidor Model Context Protocol para Semilla ERP. Permite que clientes MCP como Claude Desktop, Claude Code y otros LLMs puedan consultar y operar tu ERP en lenguaje natural.

Resumen: con este servidor instalado, podés decirle a Claude cosas como "facturame al cliente Pérez 3 mesas a $50.000", "abrime la mesa 4 y agregale 2 milanesas" o "mostrame el resumen de ventas del mes", y Claude lo ejecuta directamente contra tu ERP.

Tools incluidas

El servidor expone más de 90 tools agrupadas por módulo:

| Módulo | Tools | Ejemplos | |---|---|---| | Sesión | 3 | login_semilla, logout_semilla, estado_sesion | | Productos e inventario | 9 | buscar_productos, get_stock, ajustar_stock, get_movimientos_stock | | Ventas | 4 | get_ventas, preview_crear_orden_venta, confirmar_crear_orden_venta | | Compras | 4 | get_ordenes_compra, preview_crear_orden_compra, confirmar_crear_orden_compra | | Clientes y proveedores | 4 | buscar_clientes, crear_cliente, get_historial_cliente | | Contabilidad | 8 | get_diarios, crear_factura, postear_factura, registrar_pago | | Reportes contables | 4 | get_libro_iva, get_libro_diario, get_balance_sumas_saldos, get_estado_resultados | | Punto de Venta (POS) | 4 | get_sesiones_pos, get_ventas_pos, resumen_cierre_pos | | Listas de precios | 5 | resolver_precio, crear_lista_precios, agregar_regla_precio | | Imágenes de productos | 5 | subir_imagen_primaria, agregar_imagen_galeria | | Usuarios y empresas | 6 | listar_usuarios, listar_empresas, listar_sucursales | | Vertical: Gastronomía | 11 | gastro_get_mesas, gastro_abrir_mesa, gastro_pagar_mesa | | Vertical: Hotelería | 9 | hosp_get_disponibilidad, hosp_check_in, hosp_check_out | | Vertical: Salud | 10 | salud_buscar_pacientes, salud_get_agenda, salud_crear_appointment | | Vertical: Agricultura | 6 | agro_get_lotes_fefo, agro_emitir_dav, agro_recalcular_regalias | | Vertical: Logística | 6 | logis_listar_asignaciones, logis_crear_asignacion |

Requisitos

• Node.js 18 o superior
• Una cuenta activa de Semilla con acceso al ERP
• Tu email + contraseña de Semilla y el código del cliente (tenant)
• La URL de tu instancia del ERP (por ejemplo https://erp.tu-empresa.com)

El MCP soporta dos modos de autenticación:

1. Login interactivo desde el cliente MCP usando la tool login_semilla (recomendado para empezar).
2. JWT pre-generado seteado como variable de entorno (recomendado si querés que arranque ya logueado).

Instalación

Opción A — npx (recomendado)

No requiere instalación previa. Configurá tu cliente MCP con npx -y semilla-mcp (ver sección Configuración).

Opción B — Instalación global

npm install -g semilla-mcp

Opción C — Clonar el repo

git clone https://github.com/semilla-erp/semilla-mcp.git
cd semilla-mcp
npm install
npm run build

Configuración

Modo recomendado — Login interactivo desde Claude

Sólo necesitás setear SEMILLA_ERP_URL. El primer prompt que le hacés a Claude es para que se logue.

Claude Desktop

Editar ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) o el equivalente en tu sistema:

{
  "mcpServers": {
    "semilla": {
      "command": "npx",
      "args": ["-y", "semilla-mcp"],
      "env": {
        "SEMILLA_ERP_URL": "https://erp.tu-empresa.com"
      }
    }
  }
}

Reiniciar Claude Desktop. En el ícono 🔌 abajo a la derecha deberían aparecer las tools semilla.

Después, en una conversación nueva:

"Conectate a mi cuenta de Semilla. Email: [email protected], password: ********, cliente: miempresa"

Claude usa la tool login_semilla y queda autenticado para el resto de la conversación.

Claude Code

claude mcp add semilla npx -y semilla-mcp \
  -e SEMILLA_ERP_URL=https://erp.tu-empresa.com

Modo alternativo — JWT pre-generado

Si querés que arranque ya logueado (sin pedirle a Claude que haga login cada vez), generás el JWT manualmente y lo seteás en el config:

# Obtener el JWT vía curl:
curl -X POST https://erp.tu-empresa.com/api/semilla/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: miempresa" \
  -d '{"email":"[email protected]","password":"********","clientId":"miempresa"}' \
  | jq -r .token

Y agregás SEMILLA_JWT_TOKEN al config:

{
  "mcpServers": {
    "semilla": {
      "command": "npx",
      "args": ["-y", "semilla-mcp"],
      "env": {
        "SEMILLA_ERP_URL": "https://erp.tu-empresa.com",
        "SEMILLA_JWT_TOKEN": "eyJhbGciOiJIUzI1NiIsInR..."
      }
    }
  }
}

Importante: el JWT define a qué tenant y con qué permisos opera el MCP. Tratalo como una contraseña: nunca commitees el config con el token real, no lo compartas, y rotalo si lo exponés por error.

Tools de sesión

• login_semilla({ email, password, client_id }) — inicia sesión.
• logout_semilla() — cierra la sesión actual.
• estado_sesion() — verifica si hay sesión activa.

Patrón preview / confirm

Las tools que escriben datos críticos (ventas, compras, pagos, reservas, etc.) están divididas en dos pasos:

• preview_* — calcula y muestra lo que se va a crear, sin tocar el ERP.
• confirmar_* — ejecuta la acción real.

Esto hace que el LLM siempre te muestre un resumen antes de impactar tu ERP. El cliente MCP (Claude) te pide confirmación entre los dos pasos.

Ejemplos de uso

| Tu prompt | Tool que invoca | |---|---| | "¿cuánto vendí hoy?" | get_ventas | | "buscame el cliente Pérez" | buscar_clientes | | "facturale a Pérez 3 sillas a $20.000 cada una" | preview_crear_orden_venta → confirmar_crear_orden_venta → crear_factura → postear_factura | | "qué stock tengo del producto SKU-001" | get_stock | | "cerrá la mesa 4" | gastro_preview_pagar_mesa → gastro_confirmar_pagar_mesa | | "hay habitaciones libres del 10 al 15?" | hosp_get_disponibilidad | | "agendame turno con la Dra. López el lunes a las 10" | salud_preview_crear_appointment → salud_confirmar_crear_appointment |

Desarrollo

npm run dev      # tsx watch — recarga al guardar
npm run build    # tsc → dist/
npm run inspect  # abre el MCP Inspector contra el server local

Agregar una tool nueva

1. Crear src/tools/<modulo>.ts con un array <modulo>Tools: Tool[] y handlers handleXxx.
2. Importar y registrar en 3 puntos de src/index.ts:
   • import arriba
   • ...miModuloTools en ListToolsRequestSchema
   • case 'mi_tool': return await handleMiTool(safeArgs); en el switch

Naming: tools en snake_case español, handlers en handleCamelCase.

Seguridad

• El JWT da acceso al tenant y módulos para los que se generó. No da acceso administrativo cross-tenant.
• Las tools de escritura crítica usan el patrón preview/confirm para que veas qué va a pasar antes de ejecutar.
• Las tools de datos sensibles (recetas médicas, historias clínicas) son solo lectura en este MCP. Las acciones críticas legales se hacen siempre desde la app web.
• El servidor corre localmente en tu máquina (stdio). No hay servidor intermedio entre tu cliente MCP y el ERP.

Licencia

MIT

Soporte

• Documentación de Semilla: https://semilla.biz/documentacion
• Documentación del MCP: https://semilla.biz/documentacion/semilla-mcp
• Issues: https://github.com/semilla-erp/semilla-mcp/issues