Frihet MCP Server

El primer servidor MCP nativo de IA para un ERP español. Crea facturas, gestiona gastos, rastrea clientes, maneja productos, presupuestos y webhooks, todo mediante lenguaje natural con cualquier asistente de IA. 31 herramientas, bilingüe ES/EN.

GitHub

Documentación

Servidor MCP nativo con IA para gestión empresarial.
Servidor MCP nativo con IA para gestión empresarial.

_{Funciona con Claude · ChatGPT · Cursor · Windsurf · Cline · Antigravity · Codex · Copilot · Gemini CLI — y cualquier cliente compatible con MCP.}

Frihet MCP — talk to your ERP in natural language

Distribución

Canal	Estado	Instalación
npm	Activo	`npx @frihet/mcp-server`
Endpoint remoto	Activo	`https://mcp.frihet.io/mcp` (sin instalación, OAuth o clave API)
Smithery	Activo	smithery.ai/servers/frihet/frihet-mcp
Registro MCP	Activo	registry.modelcontextprotocol.io
Registro MCP de GitHub	Activo	github.com/mcp/io.frihet/erp
Glama	Activo	glama.ai/mcp/servers/Frihet-io/frihet-mcp
mcp.so	Auto-indexado (sin verificar)	mcp.so — indexa desde npm + GitHub
PulseMCP	Auto-indexado (sin verificar)	pulsemcp.com — indexa desde npm + GitHub
Cursor Marketplace	Próximamente	cursor.com/marketplace
ChatGPT Apps	Próximamente	chatgpt.com
Directorio de Anthropic Claude	Próximamente	claude.ai/settings/connectors

Fuente de verdad: el catálogo contiene 156 operaciones canónicas. El perfil completo local sirve 161 nombres de herramientas, 11 recursos y 10 prompts (156 operaciones canónicas más 5 alias fiscales). El perfil agrupado alojado sirve 164 nombres de herramientas, 7 recursos y 10 prompts (los mismos nombres más 3 herramientas de descubrimiento, con recursos respaldados por API mantenidos solo en local). El perfil de OpenAI revisado por separado sirve 33 nombres de herramientas, 0 recursos y 0 prompts. La pertenencia al catálogo no es una garantía de que una API de respaldo esté habilitada para cada espacio de trabajo.

Qué es esto

Un servidor MCP que conecta tu asistente de IA a Frihet. Crea facturas hablando. Consulta gastos en lenguaje natural. Gestiona todo tu negocio desde tu IDE.

You:     "Create an invoice for TechStart SL, 40 hours of consulting at 75 EUR/hour, due March 1st"
Claude:  Done. Invoice INV-2026-089 created. Total: 3,000.00 EUR + 21% IVA = 3,630.00 EUR.

156 operaciones canónicas. Cinco alias fiscales. Diez prompts. El paquete local sirve 11 recursos; el Worker alojado sirve deliberadamente los 7 recursos estáticos, mientras que los recursos de espacio de trabajo respaldados por API permanecen solo en el perfil local.

Pruébalo al instante (sin registro)

Ponlo a prueba sin configuración — sin cuenta, sin clave API:

FRIHET_DEMO=1 npx -y @frihet/mcp-server

En modo demo, el servidor responde con ejemplos ficticios realistas (facturas españolas con IVA/IGIC, gastos, clientes, productos, una cuenta bancaria y más) — cada registro usa IDs con prefijo demo_ y el servidor imprime un banner de DEMO MODE al iniciar. No se persiste nada y nunca se realiza ninguna llamada de red. Las escrituras se simulan y las acciones fiscales (factura electrónica, VeriFactu, TicketBAI, FACe, nóminas) devuelven una simulación claramente etiquetada — nunca un envío real a ninguna autoridad tributaria.

Cuando estés listo para tus datos reales, elimina la bandera y añade tu clave (app.frihet.io → Configuración → Claves API). Consulta Instalación a continuación.

Para agentes de IA

Si eres un agente leyendo este repositorio en lugar de una persona leyendo una página, todo lo que necesitas es legible por máquina y se genera desde el servidor en ejecución — no tienes que analizar este README.

Qué	Dónde
Contrato de incorporación: guía rápida por cliente, autenticación, flujo de trabajo seguro, listas de herramientas con autoridad humana, recuperación de errores	`docs/agent-onboarding.json` — también incluido dentro del paquete npm
Verdad de capacidad por herramienta: `callability`, `writesFrihet`, `externalInteraction`, `externalSideEffects`	`_meta["io.frihet/capability"]` en cada entrada de `tools/list`
Cómo comportarse una vez conectado	la cadena `instructions` devuelta por `initialize` — tu cliente te la entrega automáticamente

Tres reglas que el contrato codifica, en resumen:

Orientarse antes de actuar. get_business_context y el recurso frihet://tax/rates deciden el tratamiento fiscal correcto. No recuerdes una tasa impositiva española de memoria.
Redactar, mostrar, detenerse. create_invoice, create_quote y create_credit_note tienen como valor predeterminado status=draft — sin número fiscal, sin hash, nada enviado a una autoridad tributaria. Presenta el borrador y devuelve el control.
La autoridad humana no es tuya para asumir. Cualquier herramienta con un externalSideEffects no vacío llega a la bandeja de entrada de un cliente, un webhook, dinero o AEAT / VeriFactu / TicketBAI / FACe. Varias también aceptan confirm=true; esa bandera registra una decisión humana — nunca la establezcas para satisfacer tu propio plan.

docs/agent-onboarding.json se regenera desde la superficie en vivo mediante npm run generate:agent-onboarding y se controla en CI mediante npm run gate:agent-onboarding, por lo que sus listas de herramientas y recuentos no pueden desviarse del servidor.

Instalación

Una línea (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI y más)

npx skills add Frihet-io/frihet-mcp

Plugin de Claude Code (skill + servidor MCP en una sola instalación)

Este repositorio también es un plugin de Claude Code (frihet-erp): instalarlo conecta tanto la skill de gestión empresarial como el servidor MCP.

# Try it locally
claude --plugin-dir /path/to/frihet-mcp

La disponibilidad en el marketplace está pendiente. Usa el comando de plugin local anterior o el comando MCP de Claude Code a continuación para conectarte hoy.

Invocación de la skill: /frihet-erp:frihet-mcp. El .mcp.json incluido lanza @frihet/mcp-server mediante npx — establece FRIHET_API_KEY en tu entorno (consíguela en app.frihet.io → Configuración → Claves API).

La vista previa del plugin portable de Claude incluye skills reales de cuentas por cobrar, redacción de documentos y revisión mensual con el MCP remoto público existente. Carga plugins/claude/frihet-erp en Claude Code o sube un ZIP de esa carpeta en el chat/Cowork. Sus skills guían el comportamiento; no filtran el catálogo alojado ni establecen la aprobación del Directorio. La configuración MCP local raíz anterior mantiene su configuración de clave API existente.

Claude Code — un comando

claude mcp add frihet -s user -e FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
claude mcp list          # verify: frihet ✓ Connected

La CLI es dueña del archivo de configuración, por lo que no hay nada que editar manualmente ni rutas que puedan fallar. (El ámbito de usuario escribe ~/.claude.json, no ~/.claude/mcp.json).

Codex CLI — un comando

codex mcp add frihet --env FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
codex mcp list           # verify

La configuración de Codex es TOML, no JSON. codex mcp add escribe:

[mcp_servers.frihet]
command = "npx"
args = ["-y", "@frihet/mcp-server"]

[mcp_servers.frihet.env]
FRIHET_API_KEY = "fri_your_key_here"

Pegar un bloque JSON mcpServers en ~/.codex/config.toml es un error de análisis TOML que derriba toda tu configuración de Codex, no solo este servidor. Usa el comando anterior.

Claude Desktop, Cursor, Windsurf, Cline — configuración JSON

{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server"],
      "env": {
        "FRIHET_API_KEY": "fri_your_key_here"
      }
    }
  }
}

Herramienta	Archivo de configuración
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`
Cursor	`.cursor/mcp.json` o `~/.cursor/mcp.json`
Windsurf	`~/.windsurf/mcp.json`
Cline	Configuración de VS Code o `.cline/mcp.json`

El JSON anterior es idéntico para estos cuatro clientes; solo cambia la ruta del archivo. Claude Code y Codex no están en esta tabla — gestionan su propia configuración mediante los comandos CLI mostrados anteriormente.

Remoto (sin instalación)

Usa el endpoint alojado en mcp.frihet.io — cero dependencias locales, se ejecuta en Cloudflare Workers.

Con clave API:

{
  "mcpServers": {
    "frihet": {
      "type": "streamable-http",
      "url": "https://mcp.frihet.io/mcp",
      "headers": {
        "Authorization": "Bearer fri_your_key_here"
      }
    }
  }
}

Con OAuth 2.0 + PKCE (inicio de sesión basado en navegador, sin necesidad de clave API):

Los clientes que admiten OAuth (Claude Desktop, Smithery, etc.) pueden conectarse directamente a https://mcp.frihet.io/mcp y autenticarse mediante el navegador. El servidor implementa el flujo completo de código de autorización OAuth 2.1 con PKCE.

Obtén tu clave API

Inicia sesión en app.frihet.io
Ve a Configuración > API
Haz clic en Crear clave API
Copia la clave (empieza con fri_) — solo se muestra una vez

Lo que puedes hacer

Habla con tu ERP. Estos son prompts reales, no texto de marketing.

Facturación

"Show me all unpaid invoices"
"Create an invoice for Acme SL with 10h of consulting at 95/hour"
"Mark invoice abc123 as paid"
"How much has ClientName been invoiced this year?"

Gastos

"Log a 59.99 EUR expense for Adobe Creative Cloud, category: software, tax-deductible"
"List all expenses from January"
"What did I spend on travel last quarter?"

Clientes

"Add a new client: TechStart SL, NIF B12345678, email admin@techstart.es"
"Show me all my clients"
"Update ClientName's address to Calle Mayor 1, Madrid 28001"

CRM

"Add a contact to Acme SL: Ana Garcia, CTO, ana@acme.es"
"Log a call with TechStart: discussed Q2 proposal, they're interested in upgrade"
"Add a note to ClientName: prefers invoices in English, payment NET 30"
"Show me all activities for Acme SL"

Presupuestos

"Create a quote for Design Studio: logo design (2000 EUR) + brand guidelines (3500 EUR)"
"Show me all pending quotes"

Webhooks

"Set up a webhook to notify https://my-app.com/hook when invoices are paid"
"List all my active webhooks"

Qué esperar

Este MCP es una interfaz de datos estructurada — describes lo que quieres en lenguaje natural y la IA crea, consulta o modifica registros comerciales en Frihet. La mayoría de las 156 operaciones canónicas son operaciones CRUD sobre la API REST; el resto son resúmenes de solo lectura y acciones fiscales/de factura electrónica. Los nombres de alias y descubrimiento se cuentan por separado.

Funciona muy bien:

"Create an invoice for TechStart SL, 40h consulting at 75 EUR/h"   --> creates the invoice
"Show unpaid invoices over 1,000 EUR"                               --> queries and filters
"Log a 120 EUR expense for the Madrid train, category: travel"      --> records the expense
"Update client Acme's email to billing@acme.es"                     --> modifies the record

No hace:

OCR o escaneo de PDF — no puedes subir una imagen de factura y hacer que la lea
Carga de archivos o gestión de adjuntos
Procesamiento de imágenes de ningún tipo

Si necesitas digitalizar facturas o recibos en papel, extrae los datos primero (por ejemplo, Claude Vision API, un servicio OCR dedicado o entrada manual), y luego usa el MCP para crear el registro:

1. Scan/photograph the invoice
2. Use Claude Vision: "Read this invoice image and extract the vendor, items, amounts, and dates"
3. Then: "Create an expense in Frihet for [extracted data]"

Operaciones del catálogo (156)

Facturas (12)

Herramienta	Qué hace
`list_invoices`	Lista facturas con paginación
`get_invoice`	Obtiene detalles completos de una factura por ID
`create_invoice`	Crea una nueva factura con líneas de detalle
`update_invoice`	Actualiza cualquier campo de una factura
`delete_invoice`	Elimina una factura borrador; una enviada/pagada se cancela, no se destruye (se requiere `confirm=true`)
`search_invoices`	Busca facturas por nombre de cliente, fecha o estado
`send_invoice`	Envía factura por correo al cliente (adjunto PDF) — llega a un tercero, se requiere `confirm=true`
`mark_invoice_paid`	Marca una factura como pagada con fecha de pago opcional
`get_invoice_pdf`	Obtiene bytes de PDF de factura limitados como base64
`get_invoice_einvoice`	Obtiene bytes de XML o PDF Factur-X limitados para una factura
`create_credit_note`	Crea una nota de crédito vinculada a una factura existente
`apply_late_fee`	Aplica un recargo por mora a una factura vencida

Gastos (5)

Herramienta	Qué hace
`list_expenses`	Lista gastos con paginación
`get_expense`	Obtiene detalles de un gasto
`create_expense`	Registra un nuevo gasto
`update_expense`	Modifica un gasto
`delete_expense`	Elimina un gasto

Clientes (5)

Herramienta	Qué hace
`list_clients`	Lista todos los clientes
`get_client`	Obtiene detalles de un cliente
`create_client`	Registra un nuevo cliente
`update_client`	Actualiza información de un cliente
`delete_client`	Elimina un cliente

CRM: Contactos (3)

Herramienta	Qué hace
`list_client_contacts`	Lista todos los contactos de un cliente
`create_client_contact`	Añade una persona de contacto a un cliente
`delete_client_contact`	Elimina un contacto de un cliente

CRM: Actividades (2)

Herramienta	Qué hace
`list_client_activities`	Lista actividades de CRM (llamadas, correos, reuniones, tareas)
`log_client_activity`	Registra una llamada, correo, reunión o tarea contra un cliente

CRM: Notas (3)

Herramienta	Qué hace
`list_client_notes`	Lista todas las notas de un cliente
`create_client_note`	Añade una nota de formato libre a un cliente
`delete_client_note`	Elimina una nota de un cliente

Productos (5)

Herramienta	Qué hace
`list_products`	Listar productos y servicios
`get_product`	Obtener detalles de un producto
`create_product`	Añadir un producto o servicio
`update_product`	Actualizar precios o detalles
`delete_product`	Eliminar un producto

Presupuestos (6)

Herramienta	Qué hace
`list_quotes`	Listar todos los presupuestos
`get_quote`	Obtener detalles de un presupuesto
`create_quote`	Redactar un nuevo presupuesto
`update_quote`	Modificar un presupuesto
`delete_quote`	Eliminar solo un borrador limpio sin entrega, respuesta, adjunto o evidencia de conversión; rechazar borradores protegidos; cancelar no-borradores (`confirm=true` requerido)
`send_quote`	Enviar presupuesto por correo al cliente para su aceptación

Webhooks (6)

Herramienta	Qué hace
`list_webhooks`	Listar webhooks configurados
`get_webhook`	Obtener detalles de un webhook
`create_webhook`	Registrar un nuevo endpoint de webhook
`update_webhook`	Modificar eventos o URL
`delete_webhook`	Eliminar un webhook
`test_webhook`	Enviar un payload de prueba a un endpoint de webhook configurado

Inteligencia (4)

Herramienta	Qué hace
`get_business_context`	Instantánea completa: perfil, plan, actividad reciente, principales clientes, mes actual
`get_monthly_summary`	P&L mensual: ingresos, gastos, beneficio, obligación fiscal, principales clientes por ingresos
`get_quarterly_taxes`	Preparación fiscal trimestral: campos del Modelo 303/130, repercutido vs. deducible, obligación
`duplicate_invoice`	Clonar una factura para facturación recurrente (copia elementos/cliente/impuestos, comienza como borrador)

Facturación Electrónica (10)

Herramienta	Qué hace
`send_einvoice`	Enviar una factura en 11 formatos (XRechnung, Factur-X, FatturaPA, PEPPOL, Facturae, UBL, CII) por correo / Chorus Pro / SDI / PEPPOL / descarga
`get_einvoice_status`	Consultar el estado de ejecución del flujo de trabajo Hatchet hasta que tenga éxito o falle — devuelve ackId, URL XML, URL PDF/A-3
`validate_einvoice_xml`	Validar XML sin procesar contra el esquema del formato + reglas schematron (KOSIT / Mustang / XSD / Schematron)
`export_datev`	Exportar datos contables como DATEV EXTF (Buchungsstapel / Debitoren / Kreditoren) en codificación CP1252
`einvoice_export`	Exportar datos de factura electrónica en formatos legibles por máquina (JSON/XML) para archivo o integración
`face_submit`	Enviar factura a FACe (plataforma española de facturación electrónica B2G)
`face_status`	Consultar el estado de envío en FACe para una factura enviada
`ticketbai_submit`	Enviar registro fiscal TicketBAI a la autoridad tributaria del País Vasco (Hacienda)
`ticketbai_status`	Consultar el estado de envío de TicketBAI desde la autoridad tributaria vasca
`ksef_submit`	NOT_DEPLOYED — Enviar factura a KSeF (Polonia) — stub: el transporte está listo a nivel de infraestructura en Frihet-ERP pero aún no se expone como endpoint en vivo (producción condicionada al certificado KSeF); devuelve un error etiquetado como "no disponible" hasta que se active

Seguimiento de Tiempo (6)

Herramienta	Qué hace
`list_time_entries`	Listar entradas de tiempo con filtro por usuario, proyecto, rango de fechas, estado facturable
`get_time_entry`	Obtener detalles completos de una entrada de tiempo por ID
`create_time_entry`	Registrar horas para un proyecto (marca facturable, descripción, fecha)
`update_time_entry`	Actualizar cualquier campo en una entrada de tiempo existente (semántica PATCH)
`delete_time_entry`	Eliminación suave de una entrada de tiempo (confirm=true requerido)
`get_time_summary`	Agregar total de horas facturables/no facturables para un período, con groupBy opcional (usuario/proyecto/día)

Facturas Recurrentes (8)

Herramienta	Qué hace
`list_recurring_invoices`	Listar todas las plantillas de facturas recurrentes (filtrar por activas/pausadas)
`get_recurring_invoice`	Obtener detalles completos de una plantilla recurrente por ID
`create_recurring_invoice`	Crear una nueva plantilla de factura recurrente (diaria/semanal/mensual/trimestral/anual)
`update_recurring_invoice`	Actualizar campos de la plantilla — solo afecta a futuras facturas generadas
`pause_recurring_invoice`	Pausar una plantilla activa — no se generan facturas mientras esté pausada
`resume_recurring_invoice`	Reanudar una plantilla pausada — siguiente factura en el próximo ciclo programado
`delete_recurring_invoice`	Eliminar permanentemente una plantilla (confirm=true requerido)
`run_recurring_now`	Generar la siguiente factura recurrente con `confirm=true` explícito en modos completo y agrupado; la configuración del espacio de trabajo puede activar emisión fiscal, envío y webhooks

Gestión de Equipo (4)

Herramienta	Qué hace
`list_team_members`	Listar miembros activos + invitaciones pendientes (propietario excluido)
`invite_team_member`	Invitar a un nuevo miembro por correo con rol (admin/editor/contable/visor)
`update_team_member_role`	Cambiar el rol de un miembro existente (admin/editor/contable/visor)
`remove_team_member`	Eliminar un miembro del espacio de trabajo (confirm=true requerido)

Gestoría — Contables (5)

Herramienta	Qué hace
`gestoria_message_send`	Enviar un mensaje en un hilo contextual (documentRequest / filingItem / obligation)
`gestoria_messages_list`	Listar mensajes en un hilo, más recientes primero; paginar hacia atrás con `before`
`gestoria_template_create`	Crear una plantilla de solicitud de documento reutilizable con variables + desplazamiento de fecha de vencimiento
`gestoria_template_bulk_send`	Envío masivo de una plantilla a hasta 500 espacios de trabajo de clientes en una sola llamada
`gestoria_aging_consolidated`	Informe de antigüedad de cuentas por cobrar entre clientes (tramos, desglose por espacio de trabajo, principales vencidos)

Auditoría de Libro Mayor (3)

Herramienta	Qué hace
`frihet_gl_entry_approve`	Aprobar un asiento de diario del libro mayor (solo gestor/admin — ÁREA DE CONFIANZA)
`frihet_gl_entry_reject`	Rechazar un asiento del libro mayor con motivo obligatorio (ÁREA DE CONFIANZA)
`frihet_gl_entry_audit_log`	Recuperar el historial de auditoría completo de un asiento del libro mayor

Dominio del Portal de Marca Blanca (3)

Herramienta	Qué hace
`frihet_portal_domain_add`	Añadir un dominio personalizado al portal del cliente (devuelve registros DNS CNAME)
`frihet_portal_domain_verify`	Verificar la propagación DNS para un dominio de portal personalizado
`frihet_portal_domain_remove`	Eliminar un dominio de portal personalizado (revierte al subdominio Frihet predeterminado)

Autoincorporación y VIES (2)

Herramienta	Qué hace
`frihet_portal_onboard_link_generate`	Generar un enlace de autoincorporación con límite de tiempo para un cliente potencial
`frihet_tax_id_vies_lookup`	Validar un número de IVA de la UE (CIF intracomunitario) a través de VIES

IGIC — Impuesto Indirecto de Canarias (4)

Herramienta	Qué hace
`frihet_modelo_415_summary`	M415 operaciones anuales >3.005 € (equivalente canario del M347) — no desplegado, devuelve `NOT_DEPLOYED`
`frihet_modelo_425_summary`	M425 resumen anual de IGIC para empresas canarias — no desplegado, devuelve `NOT_DEPLOYED`
`frihet_modelo_418_summary`	M418 declaración mensual individual de IGIC, régimen especial del grupo de entidades — no desplegado, devuelve `NOT_DEPLOYED`
`frihet_aiem_calculate`	Cálculo de AIEM (Arbitrio sobre Importaciones) para Canarias — no desplegado, devuelve `NOT_DEPLOYED`

Impuesto sobre Sociedades (2)

Herramienta	Qué hace
`frihet_modelo_200_summary`	Modelo 200 declaración anual del IS — no desplegado, devuelve `NOT_DEPLOYED`
`frihet_modelo_202_summary`	Modelo 202 pagos fraccionados (1P/2P/3P) — no desplegado, devuelve `NOT_DEPLOYED`

Reglas de Categorización Bancaria (2)

Herramienta	Qué hace
`frihet_bank_rules_list`	Listar todas las reglas de categorización automática bancaria (condiciones + acciones + estado)
`frihet_bank_rule_create`	Crear una nueva regla para categorizar automáticamente transacciones por descripción, importe, contraparte

Depósitos (7)

Herramienta	Qué hace
`list_deposits`	Listar depósitos con paginación
`get_deposit`	Obtener detalles de un depósito por ID
`create_deposit`	Registrar un nuevo depósito de cliente
`update_deposit`	Actualizar campos de un depósito
`delete_deposit`	Eliminar un depósito (confirm=true requerido)
`apply_deposit`	Aplicar un saldo de depósito contra una factura
`refund_deposit`	Registrar un reembolso de depósito en la contabilidad de Frihet con `confirm=true`; `amount` opcional registra esa parte, la omisión registra el saldo reembolsable restante. No transfiere dinero

Proveedores (5)

Herramienta	Qué hace
`list_vendors`	Listar todos los proveedores
`get_vendor`	Obtener detalles de un proveedor
`create_vendor`	Añadir un nuevo proveedor
`update_vendor`	Actualizar información de un proveedor
`delete_vendor`	Eliminar un proveedor

Banca (5)

Herramienta	Qué hace
`list_bank_accounts`	Listar cuentas bancarias conectadas
`get_bank_account`	Obtener detalles de una cuenta bancaria
`list_transactions`	Listar transacciones bancarias con filtros
`categorize_transaction`	Asignar una categoría y tipo de gasto/ingreso a una transacción
`match_transaction_to_invoice`	Vincular una transacción bancaria a una factura existente

Fiscal — Modelos Tributarios Españoles (7)

Herramienta	Qué hace
`get_modelo_303_summary`	Declaración trimestral de IVA (Modelo 303) — repercutido vs. deducible, neto a pagar
`get_modelo_130_summary`	Pago fraccionado trimestral de IRPF para autónomos (Modelo 130)
`get_modelo_390_summary`	Resumen anual de IVA (Modelo 390)
`get_modelo_180_summary`	Resumen anual de retenciones de alquileres (Modelo 180) — no desplegado, devuelve `NOT_DEPLOYED`
`get_modelo_347_summary`	Transacciones anuales con terceros >3.005 € (Modelo 347)
`verifactu_status`	Obtener estado de envío de VeriFactu para un registro fiscal
`verifactu_resubmit`	Reenviar un registro fiscal VeriFactu rechazado
`ticketbai_status`	Consultar estado de envío de TicketBAI — referencia cruzada de Facturación Electrónica (10); NO se cuenta en los 7 de esta sección

Alquileres Vacacionales / Estancias (5)

Herramienta	Qué hace
`list_reservations`	Listar reservas de alquiler con filtros
`get_reservation`	Obtener detalles de una reserva
`create_reservation`	Crear una nueva reserva
`list_properties`	Listar todas las propiedades de alquiler
`sync_channel`	Activar sincronización de canal OTA (Airbnb, Booking.com, etc.)

TPV — Punto de Venta (4)

Herramienta	Qué hace
`list_terminals`	Listar terminales TPV registrados
`get_sale`	Obtener detalles de una transacción de venta TPV
`list_sales`	Listar ventas TPV con paginación
`refund_sale`	Emitir un reembolso para una venta TPV

Cocina / Restaurante (6)

Herramienta	Qué hace
`list_kitchen_tickets`	Listar tickets de pedido de cocina para el panel en vivo, filtrados por estado o estación
`get_kitchen_ticket`	Obtener un ticket de cocina por ID con todos sus elementos y sus estados individuales
`update_kitchen_ticket`	Avanzar el estado de un ticket (en cola → preparando → listo → servido) o reasignarlo a otra estación
`list_kitchen_stations`	Listar todas las estaciones de cocina con id, nombre y estado activo
`list_menu_items`	Listar el catálogo del menú de cocina con búsqueda de texto libre y filtro activo/inactivo
`kitchen_flow_summary`	Detección de estación lenta: agregar tickets abiertos por estación y marcar el cuello de botella

RRHH — Recursos Humanos (9)

Herramienta	Qué hace
`leave_request_create`	Crear una solicitud de ausencia (vacaciones, enfermedad, personal)
`leave_approve`	Aprobar una solicitud de ausencia pendiente
`leave_reject`	Rechazar una solicitud de ausencia con un motivo
`leave_cancel`	Cancelar una solicitud de ausencia aprobada o pendiente
`leave_list`	Listar solicitudes de ausencia con filtros (usuario, estado, rango de fechas)
`attendance_clock_in`	Registrar entrada (fichaje) de un empleado
`attendance_clock_out`	Registrar salida (fichaje) de un empleado
`overtime_report`	Leer horas extra diarias/semanales, agregar minutos/horas y alertas de cumplimiento calculadas sobre los registros YYYY o YYYY-MM seleccionados
`anomaly_list`	Listar anomalías de asistencia (fichajes faltantes, horas extra excesivas)

Nóminas (2)

Herramienta	Qué hace
`payroll_export`	Lee datos de empleados normalizados listos para nómina; el valor de formato es una etiqueta de destino reflejada, no un archivo generado
`payroll_checklist`	Lista empleados pagables con estado de preparación para nómina, campos faltantes y estado de revisión mensual

Incorporación — retirada mediante #124

Las herramientas onboarding_status y onboarding_persona_set fueron retiradas porque la familia /v1/onboarding/* de Frihet-ERP no existe en esta versión. Consulta el issue #124 para la auditoría y el precedente (src/tools/igic.ts muestra el patrón de stub en línea NOT_DEPLOYED utilizado para familias cuya API subyacente aún no se ha publicado; la incorporación optó por la retirada completa, porque el catálogo no debería prometer herramientas que no tienen un controlador activo).

Si una futura versión de Frihet-ERP publica la familia, restaura src/tools/onboarding.ts, los esquemas onboardingStatusOutput / onboardingPersonaResultOutput en src/tools/shared.ts, los métodos getOnboardingStatus / setOnboardingPersona en IFrihetClient y el registro en src/tools/register-all.ts (la prueba Onboarding tools — withdrawn via #124 en src/__tests__/d4b-hr-payroll-onboarding-tools.test.ts es la puerta que fallará y recordará al próximo mantenedor qué había aquí).

Permisos (2)

Herramienta	Qué hace
`permissions_matrix`	Obtiene la instantánea documentada del modelo RBAC (no es una garantía de autorización en tiempo de ejecución)
`permissions_me`	Compara los campos del modelo RBAC con los alcances reales de las claves API y denegaciones de alcance conocidas (no exhaustivo)

Cierre de período (3)

Herramienta	Qué hace
`period_close_status`	Obtiene el rango del año fiscal YYYY actual o seleccionado, estado abierto/cerrado y detalles de cierre anulables
`period_close`	Cierra un período contable (solo gestor/admin — ÁREA DE CONFIANZA)
`period_reopen`	Reabre un período cerrado con un motivo obligatorio (ÁREA DE CONFIANZA)

Todas las operaciones canónicas (y sus alias) devuelven salida estructurada mediante outputSchema — JSON tipado, no texto sin formato. Las formas de respuesta de listas siguen su familia de API; no todos los endpoints de listas están paginados.

Verdad de capacidad y efectos secundarios

En todas las superficies MCP, cada entrada de tools/list incluye _meta["io.frihet/capability"]:

registered significa que el nombre y el controlador existen en esta compilación del servidor;
callability es api_dependent (el controlador llama a la API; el despliegue, la habilitación del espacio de trabajo y la autorización aún deciden), runtime_checked (el controlador distingue explícitamente un backend ausente de datos vacíos), deferred, unavailable o local — nunca una afirmación incondicional de "disponible";
writesFrihet, externalInteraction y externalSideEffects distinguen cambios de estado y llamadas a entidades/proveedores externos;
Las anotaciones de acción MCP siguen siendo la fuente estándar para sugerencias de solo lectura, destructivas, idempotentes y de mundo abierto.

El host de ChatGPT/OpenAI es una superficie revisada por separado: exactamente 33 operaciones de negocio con descripciones completas, 0 herramientas de meta-descubrimiento, 0 prompts y 0 recursos. Sus 17 lecturas y 16 escrituras son deliberadamente limitadas, y todas las escrituras requieren confirm=true literal. Diez escrituras pueden entregar eventos comerciales completos a endpoints activos previamente configurados por el propietario del espacio de trabajo; la administración de webhooks en sí permanece excluida. La entrega directa de correo electrónico, el resumen mensual heredado, los PDF de facturas sin procesar, las transiciones del ciclo de vida de facturas, la actualización de una cotización existente, la presentación regulada, la eliminación de registros de clientes principales, la eliminación de gastos con sus archivos vinculados, la eliminación de productos y la eliminación de proveedores también están excluidas. Esta superficie no debe inferirse del catálogo completo.

Recursos

Contexto que la IA puede leer para tomar decisiones más inteligentes.

El paquete local sirve 11 recursos: 7 referencias estáticas más 4 recursos de espacio de trabajo respaldados por API. El Worker alojado sirve los 7 recursos estáticos. El host revisado por OpenAI sirve 0 recursos.

Estáticos (datos de referencia, sin llamadas API):

Recurso	URI	Qué proporciona
Esquema API	`frihet://api/schema`	Resumen OpenAPI: endpoints, autenticación, límites de velocidad, paginación, códigos de error
Tipos impositivos	`frihet://tax/rates`	Tipos impositivos por zona fiscal española: IVA, IGIC, IPSI, inversión del sujeto pasivo UE, IRPF
Calendario fiscal	`frihet://tax/calendar`	Plazos de presentación trimestrales y anuales para los modelos fiscales españoles enumerados
Categorías de gastos	`frihet://config/expense-categories`	8 categorías con reglas de deducibilidad, tratamiento de IVA, amortización
Estados de facturas	`frihet://config/invoice-statuses`	Flujo de estados (borrador > enviada > pagada/vencida > cancelada), reglas de transición, eventos de webhook
Monedas	`frihet://config/currencies`	40 monedas compatibles con códigos ISO, símbolos, decimales, formato de configuración regional
Países	`frihet://config/countries`	61 países compatibles con zonas fiscales, tipos impositivos predeterminados, monedas, prefijos de factura

Dinámicos (datos en vivo de tu cuenta):

Recurso	URI	Qué proporciona
Perfil de negocio	`frihet://business-profile`	Tu información de negocio, plan, valores predeterminados, actividad reciente, clientes principales
Instantánea mensual	`frihet://monthly-snapshot`	P&L del mes actual, ingresos, gastos, obligación tributaria
Facturas vencidas	`frihet://overdue-invoices`	Todas las facturas con fecha de vencimiento pasada (hasta 100)
Límites del plan	`frihet://status/plan-limits`	Nivel de plan en vivo, contadores de uso, facturas/mes, límites de velocidad de API

Prompts (10)

Flujos de trabajo preconstruidos que la IA puede ejecutar como operaciones guiadas de varios pasos.

Prompt	Qué hace	Argumentos
`monthly-close`	Cerrar el mes: revisar facturas impagadas, categorizar gastos, verificar obligaciones fiscales, generar resumen	`month?` (AAAA-MM)
`onboard-client`	Configurar un nuevo cliente con tipos impositivos correctos según ubicación, opcionalmente crear una cotización de bienvenida	`clientName`, `country?`, `region?`
`quarterly-tax-prep`	Preparar la presentación fiscal trimestral: calcular IVA/IGIC, identificar deducibles, previsualizar Modelo 303/130/420	`quarter?`, `fiscalZone?`
`overdue-followup`	Encontrar facturas vencidas, redactar mensajes de seguimiento, sugerir recordatorios de pago	--
`new-client-invoice`	Crear un cliente + primera factura en un solo flujo de trabajo con búsqueda de tipo impositivo	`clientName`, `country?`
`expense-report`	Generar informe de gastos agrupado por categoría con totales deducibles	`month?` (AAAA-MM)
`year-end-close`	Cierre anual completo: revisión trimestral, facturas pendientes, gastos sin categorizar, lista de verificación de fin de año	`year` (AAAA)
`cash-flow-forecast`	Proyectar flujo de caja para los próximos meses: ingresos recurrentes, gastos, cuentas por cobrar vencidas, plazos fiscales	`months?` (predeterminado: 3)
`invoice-aging-review`	Análisis de antigüedad de cuentas por cobrar: agrupar facturas impagadas por tramo (0-30/31-60/61-90/90+ días), principales deudores, acciones de cobro	--
`expense-batch`	Procesar gastos en lote: categorizar, aplicar tipos impositivos, marcar recibos faltantes	`fiscalZone?`

Cómo funciona

graph LR
    AI["Your AI assistant"]
    MCP["frihet-mcp"]
    API["api.frihet.io"]
    DB["Frihet ERP"]

    AI -- "create_invoice()" --> MCP
    MCP -- "POST /v1/invoices" --> API
    API --> DB
    DB -- "201 + invoice data" --> API
    API -- "structured JSON" --> MCP
    MCP -- "typed response + suggestions" --> AI

    style AI fill:#09090b,stroke:#4ade80,color:#fafafa
    style MCP fill:#09090b,stroke:#fafafa,color:#fafafa
    style API fill:#09090b,stroke:#3f3f46,color:#a1a1aa
    style DB fill:#09090b,stroke:#3f3f46,color:#a1a1aa

El servidor traduce las llamadas de herramientas en solicitudes REST API. Maneja autenticación, límites de velocidad (reintento automático con retroceso en 429), paginación y mapeo de errores.

Dos transportes:

stdio (local) -- npx @frihet/mcp-server con FRIHET_API_KEY
HTTP Streamable (remoto) -- https://mcp.frihet.io/mcp con token Bearer u OAuth 2.0+PKCE

Variables de entorno

Variable	Requerida	Predeterminado
`FRIHET_API_KEY`	Sí (stdio)	--
`FRIHET_API_URL`	No	`https://api.frihet.io/v1`
`FRIHET_TOOL_MODE`	No	`full`
`FRIHET_CLAUDE_MODE`	No (candidato local no publicado)	`false`

El candidato Claude solo de código fuente requiere compilar este checkout y ejecutar dist/index.js; no se afirma que las versiones npm existentes admitan la bandera. Consulta alcance del candidato, exclusiones y verificaciones. No se puede combinar con FRIHET_OPENAI_MODE=true y no está habilitado en el Worker desplegado.

Exposición de herramientas: profundidad servida bajo demanda

El diferenciador de Frihet es la profundidad — cobertura fiscal completa ES/UE más cumplimiento nativo (VeriFactu, TicketBAI, Facturae/FACe; infraestructura KSeF Polonia lista, activación pendiente), banca, CRM, RRHH/nómina, estancia/PMS y POS. Pero una lista plana de cada herramienta, cargada en el contexto de un agente de antemano, es el problema de pudrición de contexto de 2026: desplaza la tarea y degrada la selección de herramientas antes de que comience cualquier trabajo.

FRIHET_TOOL_MODE te permite elegir cómo se expone esa profundidad.

Modo	Comportamiento
`full` (predeterminado)	Las herramientas canónicas y los alias fiscales se exponen con descripciones y esquemas completos. Los descriptores públicos añaden verdad conservadora de capacidad y efectos secundarios; los nombres de operación, esquemas y controladores no cambian.
`grouped`	Divulgación progresiva. La descripción de cada herramienta se reduce a un `[group] summary — full schema via describe_tool('name')` de una línea, y se añaden tres herramientas de descubrimiento ligeras. El agente carga profundidad solo para las herramientas que realmente necesita.

En el modo grouped, los nombres de operación, esquemas de entrada y controladores no cambian. Los descriptores también exponen la misma verdad conservadora de capacidad y acción que el perfil completo. El descubrimiento fluye a través de tres meta-herramientas:

list_tool_groups() — el mapa de dominio (facturación, gastos, fiscal/cumplimiento, banca, CRM, RRHH/nómina, estancia/PMS, POS, inteligencia, productos, plataforma) con una descripción de una línea y recuento de herramientas para cada uno.
search_tools(query) — búsqueda de texto libre en nombre de herramienta, título, resumen y grupo; devuelve herramientas coincidentes con su grupo, resumen, bandera de solo lectura y campos de entrada. Filtro opcional group y limit.
describe_tool(name) — la descripción original completa y los campos de entrada para una herramienta, bajo demanda, antes de llamarla.

// claude_desktop_config.json — opt in to grouped mode
{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["@frihet/mcp-server"],
      "env": {
        "FRIHET_API_KEY": "fri_...",
        "FRIHET_TOOL_MODE": "grouped"
      }
    }
  }
}

La exposición agrupada cambia la densidad de descripción, no el comportamiento de la operación. El perfil versionado revisado por OpenAI se compone por separado y permanece con acceso independiente.

Límites de API

Límite	Valor
Solicitudes por minuto	100 por clave API
Resultados por página	100 máx. (50 predeterminado)
Cuerpo de solicitud	1 MB máx.
Carga útil de webhook	100 KB máx.
Webhooks por cuenta	20 máx.

El límite de velocidad se maneja automáticamente con retroceso exponencial.

Habilidad de Claude Code

Más allá de las herramientas MCP sin procesar, este repositorio incluye una habilidad de Claude Code que añade contexto de negocio: reglas fiscales españolas, recetas de flujo de trabajo, informes financieros y comandos en lenguaje natural.

Instalar la habilidad

git clone https://github.com/Frihet-io/frihet-mcp.git
ln -s "$(pwd)/frihet-mcp/skills/frihet-mcp" ~/.claude/skills/frihet-mcp

O con el instalador universal:

npx skills add Frihet-io/frihet-mcp

La habilidad enruta solicitudes a las herramientas MCP de Frihet (facturas, cotizaciones, gastos, clientes, revisión mensual) y le dice al agente cuándo pedir confirmación antes de escrituras. No añade subcomandos /frihet independientes, y no incluye tipos de IVA ni reglas de deducibilidad: las cifras fiscales provienen de tus datos de Frihet, no de la habilidad.

Documentación completa: docs.frihet.io/desarrolladores/skill-claude-code

Desarrollo

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build

Ejecutar localmente:

FRIHET_API_KEY=fri_xxx node dist/index.js

Probar con el MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue primero para discutir lo que te gustaría cambiar.

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build   # must pass before submitting

Limitaciones actuales

Sin OCR ni carga de archivos -- el MCP funciona con datos estructurados, no con imágenes o PDFs.
Empresa única -- una clave API se asigna a un espacio de trabajo de Frihet.
Se requiere cuenta de Frihet -- necesitas una cuenta activa en app.frihet.io y una clave API (comienza con fri_).

Ecosistema

Paquete	Qué es
`@frihet/mcp-server`	Este servidor MCP (156 operaciones canónicas + 5 nombres de alias; 11 recursos locales; 10 prompts)
`@frihet/sdk`	SDK de TypeScript (`frihet.invoices.create()`)
`frihet`	CLI (`frihet invoices list --status overdue`)
`n8n-nodes-frihet`	Nodo comunitario de n8n para automatización de flujos de trabajo
API REST	OpenAPI 3.1 en `api.frihet.io/v1`
MCP remoto	Endpoint alojado en Cloudflare Workers (sin instalación)
Webhooks	Eventos en tiempo real con HMAC-SHA256

Enlaces

Frihet -- El producto
Documentación -- Documentación completa
Referencia de API -- API REST
Documentación del servidor MCP -- Guías de configuración, solución de problemas
npm -- Registro de paquetes
Smithery -- Mercado de Smithery
Registro MCP -- Registro oficial del Protocolo de Contexto de Modelo
Registro MCP de GitHub -- Listado de Frihet en GitHub
Endpoint remoto -- Servidor MCP alojado (Cloudflare Workers)
Especificación OpenAPI -- Definición de API legible por máquina
Política de seguridad -- Guía para reportar vulnerabilidades de forma privada

Licencia

MIT. Ver LICENSE.

Creado por Frihet.