mcp-malt

Un servidor MCP para la API de Malt. Cubre las 13 operaciones que publica Malt: las facturas que emites, la comisión que Malt te cobra, los pagos que recibes y el aprovisionamiento de usuarios SCIM para cuentas de organización.

Qué cubre y qué no cubre

La API de Malt es más pequeña de lo que la mayoría espera. Cubre la facturación de back office y el aprovisionamiento de usuarios empresarial, y nada más:

No hay búsqueda de talento, ni perfiles, ni proyectos, ni ofertas, ni mensajes. Eso es por lo que se conoce a Malt, y nada de eso está en la API pública. Si has venido a por eso, este servidor no puede proporcionártelo, ni tampoco nada construido sobre la API documentada.

Dos servidores comunitarios de MCP para Malt sí acceden a esos datos, manejando la aplicación web con automatización de navegador y raspando el DOM. Su propia documentación advierte de que automatizar las ediciones de perfil puede vulnerar los términos de servicio de Malt. Este servidor solo llama a la API documentada.

Related MCP server: fintaro-mcp

Cómo obtener un token

1. Crea una identidad en la página de registro si no tienes una.

2. Abre Mi cuenta y luego Claves de API.

3. Crea un token de acceso con los alcances de permisos que necesites. Haz que coincidan con los conjuntos de herramientas que planees activar.

4. Copia el token sin demora. Se muestra una sola vez, al crearlo, y nunca más.

Los tokens de las cuentas gratuitas son de autoservicio. Los tokens de los equipos de clientes y de las organizaciones, que necesita el conjunto de scim, se obtienen a través de tu representante de Malt.

No hay OAuth 2.0 aquí. Malt no publica ningún servidor de autorización ni un endpoint de de tokens, así que el token de API anterior es la única vía de entrada. docs/authentication.md explica esto con más detalle, incluido el detalle de la cabecera que hace tropezar a la mayoría.

Instalación

Publicado de tres maneras a partir de un único lanzamiento: el paquete npm de npm y en GitHub Packages, y la imagen de contenedor en GHCR. npx es opción habitual para un cliente MCP; Docker encaja en un entorno bloqueado o compartido.

Para instalarlo desde GitHub Packages en lugar de npmjs, apunta el ámbito a el repositorio: @ialejandro:registry=https://npm.pkg.github.com en tu .npmrc.

npx

// Claude Desktop: claude_desktop_config.json
// Cursor: .cursor/mcp.json
{
  "mcpServers": {
    "malt": {
      "command": "npx",
      "args": ["-y", "@ialejandro/mcp-malt"],
      "env": {
        "MALT_API_TOKEN": "your-token-here",
        "MALT_TOOLSETS": "invoices,payments,fee-invoices"
      }
    }
  }
}

Claude Code

claude mcp add malt \
  --env MALT_API_TOKEN=your-token-here \
  --env MALT_TOOLSETS=invoices,payments,fee-invoices \
  -- npx -y @ialejandro/mcp-malt

Docker

El servidor habla JSON-RPC por stdin y stdout, por lo que -i es obligatorio y hay que omitir -t.

docker run -i --rm \
  -e MALT_API_TOKEN=your-token-here \
  -e MALT_TOOLSETS=invoices \
  ghcr.io/ialejandro/mcp-malt

// Claude Desktop: claude_desktop_config.json
// Cursor: .cursor/mcp.json
{
  "mcpServers": {
    "malt": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MALT_API_TOKEN",
        "-e", "MALT_TOOLSETS",
        "ghcr.io/ialejandro/mcp-malt"
      ],
      "env": {
        "MALT_API_TOKEN": "your-token-here",
        "MALT_TOOLSETS": "invoices,payments,fee-invoices"
      }
    }
  }
}

Desde el código fuente

git clone https://github.com/ialejandro/mcp-malt
cd mcp-malt
npm ci && npm run build

{
  "mcpServers": {
    "malt": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-malt/dist/index.js"],
      "env": {
        "MALT_API_TOKEN": "your-token-here",
        "MALT_TOOLSETS": "invoices,payments,fee-invoices"
      }
    }
  }
}

{
  "mcpServers": {
    "malt": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MALT_API_TOKEN",
        "-e", "MALT_TOOLSETS",
        "ghcr.io/ialejandro/mcp-malt"
      ],
      "env": {
        "MALT_API_TOKEN": "your-token-here",
        "MALT_TOOLSETS": "invoices,payments,fee-invoices"
      }
    }
  }
}

Configuración

Sin MALT_TOOLSETS, el servidor arranca y no ofrece nada. Es una decisión deliberada, no un fallo: tú decides qué debería ver un modelo. Añade los conjuntos de herramientas de uno en uno.

Un nombre de conjunto de herramientas desconocido detiene el servidor con un error en lugar de ignorarse, porque un tipográfico que te cueste silenciosamente tres herramientas es muy difícil de depurar.

Tareas habituales

Reconciliar un trimestre. Habilita invoices,payments,fee-invoices и ejecuta el prompt malt_reconcile_revenue. Recoge las tres, empareja los pagos con las facturas que liquidan e info de los importes brus: bruto facturado, impuestos, comisión de Malt y efectivo recibido.

Concilia mis ingresos de Malt para el primer trimestre de 2026.

Obtener un PDF de fact. Malt devuelve los PDF codificados en base64 dentro de un cuerpo JSON. Las herramientas los decodifican y devuelven un adjunto PDF real.

Descarga el PDF de la factura INV-123456.

Dar de baja a alguien. Activa scim con MALT_ALLOW_WRITES=true y utiliza malt_user_lifecycle. Desactiva en lugar de eliminar, que es el camino que Malt realmente soporta.

Dar de baja a jane.doe@acme.com de nuestra organización de Malt.

Documentación

• Obtener y gestionar un token

• Autenticación y por qué no hay OAuth

• Conjuntos de herramientas: qué habilitar y cuándo

• Todos los endpoints, con peticiones y respuestas

• Errores y su significado

• Límites de tasa

• Extender el servidor

Desarrollo

npm ci
npm run typecheck
npm test
npm run build
npm run check-spec   # diff the live Malt spec against spec/malt-openapi.json

Las pruebas simulación de fetch y nunca llaman a la API real.

spec/malt-openapi.json es una instantánea confirmada del documento publicado de Malt. Un flujo de trabajo diario compara el spec en vivo con él y abre una PR cuando algo se mueve. Malt ha mantenido info.version en 0.0.1 durante todo el proceso, por lo que check compara operaciones por su lugar de confiar en el número de versión.

Contribuciones

Ver CONTRIBUTING.md. Agregar un endpoint o un conjunto de herramientas se describe en docs/extending.md.

Licencia

MIT