Lets an AI client interact with Freemática ERP to manage invoicing, receivables, suppliers, accounting, and HR data.
Also known as nubiia-dev/mcp-freematica, @nubiia/mcp-freematica
- Stars
- 0
- Tools
- 66
- Downloads, 30 days
- —
- Latest version
- 0.11.2
- Last commit
- Oct 22, 2026
- License
- MIT
What is Freemática MCP?
Freemática lets an AI client interact with Freemática ERP to manage invoicing, receivables, suppliers, accounting, and HR data. It exposes 66 tools, such as freematica_list_articulos, freematica_get_articulo, freematica_get_precio_articulo.
Summary generated from the project's README
About Freemática MCP server
Managing business operations through an AI assistant is possible by connecting your client to the Freemática ERP via this MCP server. It allows developers and business users to interact with core enterprise data including invoicing, receivables, suppliers, accounting, and human resources. By exposing the Freemática REST API, the server enables an AI to perform complex data retrieval tasks across various business modules.
The server operates using TypeScript and Node.js, supporting both stdio and Streamable HTTP transports. Users can utilize specific tools to query information such as product catalogs with freematica_list_articulos, check client details with freematica_get_cliente, or manage human resources through freematica_list_personal. It also provides access to financial data like accounting entries via freematica_export_asientos and sales invoice details through freematica_list_factura_lineas.
This integration transforms a standard AI client into a functional business interface. Instead of manual database lookups, you can ask your assistant to list unpaid client documents using freematica_list_cartera_clientes or retrieve specific purchase order details with freematica_get_pedido_compra. This setup requires a connection to the Freemática API to function.
Written from the project's README. Every use case is checked against a quote from it.
How to install Freemática MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Freemática MCP in Claude Code
$ claude mcp add --env 'FREEMATICA_AUTH_SESSION=<YOUR_FREEMATICA_AUTH_SESSION>' --env 'FREEMATICA_AUTH_TOKEN=<YOUR_FREEMATICA_AUTH_TOKEN>' --env 'FREEMATICA_AUTH_APP=<FREEMATICA_AUTH_APP>' --env 'FREEMATICA_AUTH_COMPANY=<FREEMATICA_AUTH_COMPANY>' --env 'FREEMATICA_AUTH_ORGANIZATION=<FREEMATICA_AUTH_ORGANIZATION>' mcp-freematica -- npx -y @nubiia/mcp-freematicaInstall Freemática MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-freematica": {
"command": "npx",
"args": [
"-y",
"@nubiia/mcp-freematica"
],
"env": {
"FREEMATICA_AUTH_SESSION": "<YOUR_FREEMATICA_AUTH_SESSION>",
"FREEMATICA_AUTH_TOKEN": "<YOUR_FREEMATICA_AUTH_TOKEN>",
"FREEMATICA_AUTH_APP": "<FREEMATICA_AUTH_APP>",
"FREEMATICA_AUTH_COMPANY": "<FREEMATICA_AUTH_COMPANY>",
"FREEMATICA_AUTH_ORGANIZATION": "<FREEMATICA_AUTH_ORGANIZATION>"
}
}
}
}Install Freemática MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-freematica": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@nubiia/mcp-freematica"
],
"env": {
"FREEMATICA_AUTH_SESSION": "<YOUR_FREEMATICA_AUTH_SESSION>",
"FREEMATICA_AUTH_TOKEN": "<YOUR_FREEMATICA_AUTH_TOKEN>",
"FREEMATICA_AUTH_APP": "<FREEMATICA_AUTH_APP>",
"FREEMATICA_AUTH_COMPANY": "<FREEMATICA_AUTH_COMPANY>",
"FREEMATICA_AUTH_ORGANIZATION": "<FREEMATICA_AUTH_ORGANIZATION>"
}
}
}
}Install Freemática MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-freematica","type":"stdio","command":"npx","args":["-y","@nubiia/mcp-freematica"],"env":{"FREEMATICA_AUTH_SESSION":"<YOUR_FREEMATICA_AUTH_SESSION>","FREEMATICA_AUTH_TOKEN":"<YOUR_FREEMATICA_AUTH_TOKEN>","FREEMATICA_AUTH_APP":"<FREEMATICA_AUTH_APP>","FREEMATICA_AUTH_COMPANY":"<FREEMATICA_AUTH_COMPANY>","FREEMATICA_AUTH_ORGANIZATION":"<FREEMATICA_AUTH_ORGANIZATION>"}}'Install Freemática MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-freematica": {
"command": "npx",
"args": [
"-y",
"@nubiia/mcp-freematica"
],
"env": {
"FREEMATICA_AUTH_SESSION": "<YOUR_FREEMATICA_AUTH_SESSION>",
"FREEMATICA_AUTH_TOKEN": "<YOUR_FREEMATICA_AUTH_TOKEN>",
"FREEMATICA_AUTH_APP": "<FREEMATICA_AUTH_APP>",
"FREEMATICA_AUTH_COMPANY": "<FREEMATICA_AUTH_COMPANY>",
"FREEMATICA_AUTH_ORGANIZATION": "<FREEMATICA_AUTH_ORGANIZATION>"
}
}
}
}Install Freemática MCP in Codex
$ codex mcp add mcp-freematica --env 'FREEMATICA_AUTH_SESSION=<YOUR_FREEMATICA_AUTH_SESSION>' --env 'FREEMATICA_AUTH_TOKEN=<YOUR_FREEMATICA_AUTH_TOKEN>' --env 'FREEMATICA_AUTH_APP=<FREEMATICA_AUTH_APP>' --env 'FREEMATICA_AUTH_COMPANY=<FREEMATICA_AUTH_COMPANY>' --env 'FREEMATICA_AUTH_ORGANIZATION=<FREEMATICA_AUTH_ORGANIZATION>' -- npx -y @nubiia/mcp-freematicaInstall Freemática MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-freematica] command = "npx" args = ["-y", "@nubiia/mcp-freematica"] [mcp_servers.mcp-freematica.env] FREEMATICA_AUTH_SESSION = "<YOUR_FREEMATICA_AUTH_SESSION>" FREEMATICA_AUTH_TOKEN = "<YOUR_FREEMATICA_AUTH_TOKEN>" FREEMATICA_AUTH_APP = "<FREEMATICA_AUTH_APP>" FREEMATICA_AUTH_COMPANY = "<FREEMATICA_AUTH_COMPANY>" FREEMATICA_AUTH_ORGANIZATION = "<FREEMATICA_AUTH_ORGANIZATION>"
Install Freemática MCP in Gemini CLI
$ gemini mcp add -s user -e 'FREEMATICA_AUTH_SESSION=<YOUR_FREEMATICA_AUTH_SESSION>' -e 'FREEMATICA_AUTH_TOKEN=<YOUR_FREEMATICA_AUTH_TOKEN>' -e 'FREEMATICA_AUTH_APP=<FREEMATICA_AUTH_APP>' -e 'FREEMATICA_AUTH_COMPANY=<FREEMATICA_AUTH_COMPANY>' -e 'FREEMATICA_AUTH_ORGANIZATION=<FREEMATICA_AUTH_ORGANIZATION>' mcp-freematica npx -- -y @nubiia/mcp-freematicaInstall Freemática MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-freematica": {
"command": "npx",
"args": [
"-y",
"@nubiia/mcp-freematica"
],
"env": {
"FREEMATICA_AUTH_SESSION": "<YOUR_FREEMATICA_AUTH_SESSION>",
"FREEMATICA_AUTH_TOKEN": "<YOUR_FREEMATICA_AUTH_TOKEN>",
"FREEMATICA_AUTH_APP": "<FREEMATICA_AUTH_APP>",
"FREEMATICA_AUTH_COMPANY": "<FREEMATICA_AUTH_COMPANY>",
"FREEMATICA_AUTH_ORGANIZATION": "<FREEMATICA_AUTH_ORGANIZATION>"
}
}
}
}Freemática MCP tools 66
Detected from the READMEfreematica_list_articulosfreematica_get_articulofreematica_get_precio_articulofreematica_list_materiales_asignados_serviciosfreematica_get_master_datafreematica_list_clientesfreematica_get_clientefreematica_list_contactos_clientesfreematica_list_oportunidades_negociofreematica_get_oportunidad_negociofreematica_get_oportunidad_negocio_datos_ampliadosfreematica_get_ficha_prev_cliente
| freematica_list_articulos | — | |
| freematica_get_articulo | — | |
| freematica_get_precio_articulo | — | |
| freematica_list_materiales_asignados_servicios | — | |
| freematica_get_master_data | — | |
| freematica_list_clientes | — | |
| freematica_get_cliente | — | |
| freematica_list_contactos_clientes | — | |
| freematica_list_oportunidades_negocio | — | |
| freematica_get_oportunidad_negocio | — | |
| freematica_get_oportunidad_negocio_datos_ampliados | — | |
| freematica_get_ficha_prev_cliente | — |
Show all 66 toolsShow fewer tools
freematica_list_vigilancia_saludfreematica_get_vigilancia_saludfreematica_list_personalfreematica_get_personafreematica_list_calendariosfreematica_list_calendario_periodosfreematica_list_cartera_clientesfreematica_get_cartera_clientefreematica_list_facturas_cabecerafreematica_get_factura_cabecerafreematica_list_factura_lineasfreematica_list_factura_ivafreematica_list_factura_vencimientosfreematica_list_facturas_comprasfreematica_get_factura_comprafreematica_list_proveedoresfreematica_get_proveedorfreematica_list_localizaciones_cobro_clientesfreematica_list_localizaciones_pago_proveedoresfreematica_list_localizaciones_servicio_clientesfreematica_list_cuentas_contablesfreematica_list_cuentas_analiticasfreematica_export_asientosfreematica_list_pedidos_comprafreematica_get_pedido_comprafreematica_list_albaranes_ventasfreematica_get_albaran_ventafreematica_list_albaranes_facturafreematica_get_albaran_facturafreematica_list_resultados_facturacionfreematica_list_contratosfreematica_get_contratofreematica_list_servicios_contratofreematica_get_servicio_contratofreematica_list_contratos_opcionalesfreematica_get_contrato_opcionalesfreematica_list_localizaciones_envio_clientesfreematica_list_localizaciones_factura_clientesfreematica_create_contratofreematica_update_contratofreematica_create_servicio_contratofreematica_update_servicio_fechasfreematica_create_servicio_historico_preciosfreematica_update_servicio_historico_preciosfreematica_create_servicio_facturacion_txtfreematica_update_servicio_facturacionfreematica_create_contrato_opcionalesfreematica_update_contrato_opcionalesfreematica_create_clientefreematica_update_clientefreematica_create_contacto_clientefreematica_update_contacto_clientefreematica_create_localizacion_clientefreematica_update_localizacion_cliente
| freematica_list_vigilancia_salud | — | |
| freematica_get_vigilancia_salud | — | |
| freematica_list_personal | — | |
| freematica_get_persona | — | |
| freematica_list_calendarios | — | |
| freematica_list_calendario_periodos | — | |
| freematica_list_cartera_clientes | — | |
| freematica_get_cartera_cliente | — | |
| freematica_list_facturas_cabecera | — | |
| freematica_get_factura_cabecera | — | |
| freematica_list_factura_lineas | — | |
| freematica_list_factura_iva | — | |
| freematica_list_factura_vencimientos | — | |
| freematica_list_facturas_compras | — | |
| freematica_get_factura_compra | — | |
| freematica_list_proveedores | — | |
| freematica_get_proveedor | — | |
| freematica_list_localizaciones_cobro_clientes | — | |
| freematica_list_localizaciones_pago_proveedores | — | |
| freematica_list_localizaciones_servicio_clientes | — | |
| freematica_list_cuentas_contables | — | |
| freematica_list_cuentas_analiticas | — | |
| freematica_export_asientos | — | |
| freematica_list_pedidos_compra | — | |
| freematica_get_pedido_compra | — | |
| freematica_list_albaranes_ventas | — | |
| freematica_get_albaran_venta | — | |
| freematica_list_albaranes_factura | — | |
| freematica_get_albaran_factura | — | |
| freematica_list_resultados_facturacion | — | |
| freematica_list_contratos | — | |
| freematica_get_contrato | — | |
| freematica_list_servicios_contrato | — | |
| freematica_get_servicio_contrato | — | |
| freematica_list_contratos_opcionales | — | |
| freematica_get_contrato_opcionales | — | |
| freematica_list_localizaciones_envio_clientes | — | |
| freematica_list_localizaciones_factura_clientes | — | |
| freematica_create_contrato | — | |
| freematica_update_contrato | — | |
| freematica_create_servicio_contrato | — | |
| freematica_update_servicio_fechas | — | |
| freematica_create_servicio_historico_precios | — | |
| freematica_update_servicio_historico_precios | — | |
| freematica_create_servicio_facturacion_txt | — | |
| freematica_update_servicio_facturacion | — | |
| freematica_create_contrato_opcionales | — | |
| freematica_update_contrato_opcionales | — | |
| freematica_create_cliente | — | |
| freematica_update_cliente | — | |
| freematica_create_contacto_cliente | — | |
| freematica_update_contacto_cliente | — | |
| freematica_create_localizacion_cliente | — | |
| freematica_update_localizacion_cliente | — |
Configuration
FREEMATICA_AUTH_SESSIONRequiredSecretFreemática active session (x-auth-session header).
FREEMATICA_AUTH_TOKENRequiredSecretFreemática API token (x-auth-token header).
FREEMATICA_AUTH_APPRequiredFreemática consuming application, e.g. pvss (x-auth-app header).
FREEMATICA_AUTH_COMPANYRequiredFreemática company identifier (x-auth-company header).
FREEMATICA_AUTH_ORGANIZATIONRequiredFreemática organization identifier (x-auth-organization header).
FREEMATICA_BASE_URLFreemática API base URL. Change only for an alternative host.
FREEMATICA_ENABLE_WRITESSet to true to register the create/update tools. Read-only by default.
MCP_TRANSPORT
| Name | Description | |
|---|---|---|
| FREEMATICA_AUTH_SESSION | Freemática active session (x-auth-session header). | RequiredSecret |
| FREEMATICA_AUTH_TOKEN | Freemática API token (x-auth-token header). | RequiredSecret |
| FREEMATICA_AUTH_APP | Freemática consuming application, e.g. pvss (x-auth-app header). | Required |
| FREEMATICA_AUTH_COMPANY | Freemática company identifier (x-auth-company header). | Required |
| FREEMATICA_AUTH_ORGANIZATION | Freemática organization identifier (x-auth-organization header). | Required |
| FREEMATICA_BASE_URL | Freemática API base URL. Change only for an alternative host. | |
| FREEMATICA_ENABLE_WRITES | Set to true to register the create/update tools. Read-only by default. | |
| MCP_TRANSPORT | — |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubmcp-freematica
MCP server que expone operaciones del API REST de Freemática (ERP: facturación, cartera, proveedores, contabilidad, personal) para ser consumidas por asistentes de IA como Claude.
Built and maintained by Nubiia — automatización e integraciones con IA para negocios (MCP, Holded, Pipedrive y más). ¿Quieres algo así para tu empresa? Escríbenos en nubiia.es.
Stack
- TypeScript + Node.js ≥20
@modelcontextprotocol/sdk(stdio + Streamable HTTP transports)- Express + axios + zod
- pino (logging estructurado)
- Vitest + nock para tests
Tools expuestas
| Tool | Endpoint Freemática | Descripción |
|---|---|---|
freematica_list_articulos |
GET /part/v1/articulos |
Catálogo de artículos/materiales/consumibles (referencias, familias, proveedores) |
freematica_get_articulo |
GET /part/v1/articulos/{idreg} |
Detalle de un artículo |
freematica_get_precio_articulo |
GET /pgrl/v1/precio-articulo/{idreg} |
Precios de venta de un artículo (PRECIO_VENTA, DESCUENTO, FACTURABLE) |
freematica_list_materiales_asignados_servicios |
GET /pvss/v2/contratos-servicios-material |
Lista de material asignado a servicios |
freematica_get_master_data |
(24 endpoints según catalog) |
Devuelve un catálogo de datos maestros (tipos, geográficos, organizativos, inventario, financiero) |
freematica_list_clientes |
GET /pgrl/v2/clientes |
Lista paginada de clientes |
freematica_get_cliente |
GET /pgrl/v2/clientes/{idReg} |
Detalle de un cliente |
freematica_list_contactos_clientes |
GET /pgrl/v2/contactos-clientes |
Lista paginada de contactos |
freematica_list_oportunidades_negocio |
GET /pcrm/v2/oportunidades-negocio |
Lista paginada de oportunidades |
freematica_get_oportunidad_negocio |
GET /pcrm/v2/oportunidades-negocio/{idReg} |
Detalle de oportunidad |
freematica_get_oportunidad_negocio_datos_ampliados |
GET /pcrm/v2/oportunidades-negocio/{idReg}/datos-ampliados |
Datos ampliados (puede 404) |
freematica_get_ficha_prev_cliente |
GET /pprl/v2/ficha-prev-cliente |
Ficha PRL de un cliente |
freematica_list_vigilancia_salud |
GET /pprl/v1/vigilancia-salud |
Lista paginada de registros de Vigilancia de la Salud |
freematica_get_vigilancia_salud |
GET /pprl/v1/vigilancia-salud/{idreg} |
Detalle de un registro de Vigilancia de la Salud |
freematica_list_personal |
GET /pers/v1/personal |
Lista paginada de personas (RRHH) |
freematica_get_persona |
GET /pers/v2/personal/{idreg} |
Detalle de una persona |
freematica_list_calendarios |
GET /pgrl/v1/calendarios |
Lista paginada de calendarios laborales |
freematica_list_calendario_periodos |
GET /pgrl/v1/calendarios/{idreg}/periodos |
Periodos de un calendario laboral |
freematica_list_cartera_clientes |
GET /pcar/v1/cartera-clientes |
Lista paginada de cartera de clientes (cobros, impagados) |
freematica_get_cartera_cliente |
GET /pcar/v1/cartera-clientes/{idReg} |
Detalle de un documento de cartera |
freematica_list_facturas_cabecera |
GET /pven/v1/facturas-cabecera |
Lista paginada de facturas de ventas (cabecera) |
freematica_get_factura_cabecera |
GET /pven/v1/facturas-cabecera/{idReg} |
Detalle de una factura de venta |
freematica_list_factura_lineas |
GET /pven/v1/facturas-cabecera/{idReg}/lineas |
Líneas de detalle de una factura de venta |
freematica_list_factura_iva |
GET /pven/v1/facturas-cabecera/{idReg}/iva |
Líneas de IVA de una factura de venta |
freematica_list_factura_vencimientos |
GET /pven/v1/facturas-cabecera/{idReg}/vencimientos |
Vencimientos de cobro de una factura de venta |
freematica_list_facturas_compras |
GET /pcom/v1/facturas-cabecera |
Lista paginada de facturas de compras |
freematica_get_factura_compra |
GET /pcom/v1/facturas-cabecera/{idReg} |
Detalle de una factura de compra |
freematica_list_proveedores |
GET /pgrl/v2/proveedores |
Lista paginada de proveedores |
freematica_get_proveedor |
GET /pgrl/v2/proveedores/{idReg} |
Detalle de un proveedor |
freematica_list_localizaciones_cobro_clientes |
GET /pgrl/v2/localizaciones-cobro-clientes |
Localizaciones de cobro de clientes (SEPA, domiciliaciones) |
freematica_list_localizaciones_pago_proveedores |
GET /pgrl/v2/localizaciones-pago-proveedores |
Localizaciones de pago de proveedores |
freematica_list_localizaciones_servicio_clientes |
GET /pgrl/v2/localizaciones-servicio-clientes |
Localizaciones de servicio de clientes |
freematica_list_cuentas_contables |
GET /pcon/v2/cuentas |
Plan de cuentas contables (COD_CTA, COD_PLAN, etc.) |
freematica_list_cuentas_analiticas |
GET /pcon/v2/cuentas-analiticas |
Catálogo de cuentas analíticas |
freematica_export_asientos |
GET /pcon/v2/asientos |
Exporta asientos contables de un período (CSV/JSON) |
freematica_list_pedidos_compra |
GET /pcmp/v2/pedidos |
Lista paginada de pedidos de compra (filtros nativos + FIQL + estado enum) |
freematica_get_pedido_compra |
GET /pcmp/v2/pedidos/{idReg} |
Detalle de un pedido de compra (cabecera + proveedor + líneas) |
freematica_list_albaranes_ventas |
GET /pven/v2/albaranes-ventas |
Lista paginada de albaranes de ventas (filtros todos nativos, empresa requerido) |
freematica_get_albaran_venta |
GET /pven/v2/albaranes-ventas/{idReg} |
Detalle de un albarán de venta |
freematica_list_albaranes_factura |
GET /pven/v2/albaranes-facturas |
Lista paginada de vinculaciones albarán↔factura (idReg nativo + FIQL) |
freematica_get_albaran_factura |
GET /pven/v2/albaranes-facturas/{idReg} |
Detalle de una vinculación albarán-factura |
freematica_list_resultados_facturacion |
GET /pvss/v1/facturacion-resultados |
Resultados del proceso batch de facturación automática de vigilancia (FIQL) |
freematica_list_contratos |
GET /pvss/v1/contratos |
Lista paginada de cabeceras de contratos (solo filtros nativos: el API ignora FIQL aquí) |
freematica_get_contrato |
GET /pvss/v1/contratos (scan) |
Busca un contrato por empresa + código natural (paginación interna + filtrado en cliente) |
freematica_list_servicios_contrato |
GET /pvss/v1/contratos/{idReg}/servicios |
Servicios de un contrato |
freematica_get_servicio_contrato |
GET /pvss/v2/contratos-servicios/{idReg} |
Detalle de un servicio de contrato |
freematica_list_contratos_opcionales |
GET /ppre/v2/contratos/opcionales |
Lista paginada de opcionales de contratos |
freematica_get_contrato_opcionales |
GET /ppre/v2/contratos/opcionales/{idReg} |
Detalle de un registro de opcionales |
freematica_list_localizaciones_envio_clientes |
GET /pgrl/v2/localizaciones-envio-clientes |
Localizaciones de envío de clientes |
freematica_list_localizaciones_factura_clientes |
GET /pgrl/v2/localizaciones-factura-clientes |
Localizaciones de factura de clientes |
Tools de escritura (requieren FREEMATICA_ENABLE_WRITES=true)
Por defecto el servidor es de solo lectura. Con FREEMATICA_ENABLE_WRITES=true se registran además estas tools de creación y actualización. No existe ninguna tool de borrado. Todas las escrituras dejan log de auditoría (operación + endpoint + campos a nivel info; body completo a nivel debug).
| Tool | Endpoint Freemática | Descripción |
|---|---|---|
freematica_create_contrato |
POST /pvss/v2/contratos |
Alta de cabecera de contrato |
freematica_update_contrato |
PUT /pvss/v2/contratos/{idReg} |
Actualización de cabecera de contrato |
freematica_create_servicio_contrato |
POST /pvss/v2/contratos/{idReg}/servicios |
Alta de servicio (identificación derivada del idReg) |
freematica_update_servicio_fechas |
PUT /pvss/v2/contratos/{id}/servicio/{id} |
Fechas inicio/fin del servicio (mecanismo de baja) |
freematica_create_servicio_historico_precios |
POST /pvss/v2/contratos/{id}/servicios-historico-precios/{id} |
Alta de revisión de precios del servicio |
freematica_update_servicio_historico_precios |
PUT /pvss/v2/contratos/{id}/servicios-historico-precios/{id} |
Actualización de revisión de precios |
freematica_create_servicio_facturacion_txt |
POST /pvss/v2/contratos/{id}/servicios-facturacion-txt/{id} |
Alta de línea de texto de facturación |
freematica_update_servicio_facturacion |
PUT /pvss/v2/contratos/{id}/servicios-facturacion/{id} |
Datos de facturación del servicio (precios hora, forma de pago…) |
freematica_create_contrato_opcionales |
POST /ppre/v2/contratos/opcionales |
Alta de opcionales de contrato |
freematica_update_contrato_opcionales |
PUT /ppre/v2/contratos/opcionales/{idReg} |
Actualización de opcionales de contrato |
freematica_create_cliente |
POST /pgrl/v2/clientes |
Alta de cliente (idReg derivado de grupo+código) |
freematica_update_cliente |
PUT /pgrl/v2/clientes/{idReg} |
Actualización parcial de cliente (fetch+merge) |
freematica_create_contacto_cliente |
POST /pgrl/v2/contactos-clientes |
Alta de contacto de cliente |
freematica_update_contacto_cliente |
PUT /pgrl/v2/contactos-clientes/{idReg} |
Actualización parcial de contacto (fetch+merge) |
freematica_create_localizacion_cliente |
POST /pgrl/v2/localizaciones-{tipo}-clientes |
Alta de localización (tipo: cobro/envio/factura/servicio) |
freematica_update_localizacion_cliente |
PUT /pgrl/v2/localizaciones-{tipo}-clientes/{idReg} |
Actualización parcial de localización (fetch+merge) |
Filtros tipados (FIQL interno)
El MCP expone parámetros tipados con zod al consumidor (Claude/LLM). Internamente, el cliente los traduce a sintaxis FIQL antes de llamar al API de Freemática. El consumidor nunca ve ni escribe FIQL.
Ejemplo
// El LLM llama:
freematica_list_cartera_clientes({
empresa: '0001',
fechaDocDesde: '2026-01-01',
estado: 'pendiente',
});
// El MCP construye internamente (valores siempre entre comillas simples):
// rquery=CARCL_EMP=='0001';CARCL_FECDOC=ge='2026-01-01';CARCL_SITCAR=='1'
Ventajas del patrón
- El LLM solo necesita conocer los parámetros tipados con nombres semánticos en español.
- La complejidad de la sintaxis FIQL queda encapsulada en el adapter interno (
src/clients/fiql-builder.ts). - Los errores de validación son claros: "empresa debe ser string", no "FIQL parse error".
- Los filtros booleanos (
soloImpagados: true) se traducen automáticamente al operador FIQL correcto.
Más ejemplos
// Facturas pendientes de traspaso a contabilidad:
freematica_list_facturas_cabecera({
empresa: '0001',
traspasadoContabilidad: false,
});
// → rquery=FVC_CODEMP=='0001';FVC_TRASP_CONTAB=='0'
// Proveedor por nombre EXACTO (el API no soporta búsqueda parcial: =lk=
// responde 400 y los wildcards % devuelven 0 resultados). El filtro activo
// de proveedores post-filtra las bajas en cliente (FIQL no tiene IS NULL):
freematica_list_proveedores({
nombre: 'LEJIAS PONS S.A.',
activo: true,
});
// → rquery=NOMBRE_PRO=='LEJIAS PONS S.A.'
Modos de transporte
El binario soporta dos transportes seleccionables. La selección sigue este orden de precedencia:
- CLI flag:
--transport=<modo> - Variable de entorno:
MCP_TRANSPORT=<modo> - Default:
stdio
| Modo | Cuándo usar | Comando |
|---|---|---|
stdio |
Claude Desktop, Claude Code, ejecución local | mcp-freematica (default) o mcp-freematica --transport=stdio |
http |
Nubiia, deploy como servicio web | mcp-freematica --transport=http o MCP_TRANSPORT=http mcp-freematica |
Configurar en Claude Desktop (stdio)
Edita ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"freematica": {
"command": "npx",
"args": ["-y", "@nubiia/mcp-freematica"],
"env": {
"FREEMATICA_AUTH_TOKEN": "...",
"FREEMATICA_AUTH_COMPANY": "...",
"FREEMATICA_AUTH_ORGANIZATION": "...",
"FREEMATICA_AUTH_APP": "...",
"FREEMATICA_AUTH_SESSION": "..."
}
}
}
}
Reinicia Claude Desktop y las tools de freematica_* aparecerán disponibles.
Configurar en Claude Code (stdio)
claude mcp add freematica npx -y @nubiia/mcp-freematica \
-e FREEMATICA_AUTH_TOKEN=... \
-e FREEMATICA_AUTH_COMPANY=... \
-e FREEMATICA_AUTH_ORGANIZATION=... \
-e FREEMATICA_AUTH_APP=... \
-e FREEMATICA_AUTH_SESSION=...
Configurar en Nubiia (HTTP)
Setear MCP_TRANSPORT=http en las variables de entorno del proceso, junto a las 5 FREEMATICA_AUTH_*. Resto de variables (puerto, origins) opcionales — ver tabla en "Configuración avanzada".
Datos maestros disponibles
La tool freematica_get_master_data acepta un parámetro catalog con uno de los 24 valores siguientes. Cada uno mapea a un endpoint específico de Freemática.
catalog |
Endpoint Freemática | Contenido |
|---|---|---|
| Tipos / clasificaciones | ||
tipos-contrato |
GET /ppre/v2/tipos-contrato |
Tipos de contrato comercial |
tipo-instalacion |
GET /ppre/v1/tipo-instalacion |
Tipos de instalación física |
clases-servicios |
GET /pvss/v1/clases-servicios |
Clases de servicio operativas |
tipos-casos |
GET /pcrm/v2/tipos-casos |
Tipos de caso CRM |
subtipos-casos |
GET /pcrm/v2/subtipos-casos |
Subtipos de caso CRM |
tipos-oportunidad-negocio |
GET /pcrm/v2/tipos-oportunidad-negocio |
Tipos de oportunidad comercial |
tipos-impuestos |
GET /pgrl/v2/tipos-impuestos |
IVA, IRPF, retenciones |
naturalezas-abono |
GET /pven/v1/naturalezas-abono |
Naturalezas de abono comercial |
incidencecode |
GET /pvss/v2/incidencecode |
Códigos de incidencia en servicios |
claves-facturacion |
GET /pvss/v2/claves-facturacion |
Claves de facturación de servicios |
| Geográficos | ||
paises |
GET /pgrl/v1/paises |
Países |
nacionalidades |
GET /pgrl/v1/nacionalidades |
Nacionalidades |
provincias |
GET /pgrl/v1/provincias |
Provincias |
poblaciones |
GET /pgrl/v2/poblaciones |
Municipios |
| Organizativos | ||
empresas |
GET /pgrl/v1/empresas |
Empresas |
delegaciones |
GET /pgrl/v1/delegaciones/agrupcod |
Delegaciones (listado global) |
lineas-negocio |
GET /pgrl/v2/lineas-negocio |
Líneas de negocio |
cargos-clientes |
GET /pgrl/v2/cargos-clientes |
Cargos de contactos |
calendarios |
GET /pgrl/v1/calendarios |
Calendarios laborales |
series |
GET /pgrl/v2/series |
Series de numeración de documentos |
| Inventario | ||
familias |
GET /part/v1/familias |
Familias de artículos |
subfamilias |
GET /part/v1/subfamilias |
Subfamilias |
lineas |
GET /part/v1/lineas |
Líneas de artículos |
| Financiero | ||
bancos |
GET /pgrl/v2/bancos |
Entidades bancarias |
Respuesta: { catalog, items, count, total }. Patrón típico de uso: llamar primero al catálogo correspondiente cuando otra tool devuelva IDs crípticos para resolverlos a nombres humanos.
Paginación
Todas las tools freematica_list_* aceptan dos parámetros opcionales:
page(int, ≥1, default 1): página a recuperar, 1-indexed.items(int, 1..50, default 20): items por página.
La respuesta incluye siempre total (total de elementos en el dataset) para que el LLM pueda iterar páginas.
El parámetro está bloqueado en
page >= 1porque el API real de Freemática tratapage=0como "devuelve TODO el dataset" (varios MB en endpoints grandes comoclientes). Verificado empíricamente.
Freemática MCP questions
How do I add Freemática MCP to Claude Code?
Run claude mcp add --env 'FREEMATICA_AUTH_SESSION=<YOUR_FREEMATICA_AUTH_SESSION>' --env 'FREEMATICA_AUTH_TOKEN=<YOUR_FREEMATICA_AUTH_TOKEN>' --env 'FREEMATICA_AUTH_APP=<FREEMATICA_AUTH_APP>' --env 'FREEMATICA_AUTH_COMPANY=<FREEMATICA_AUTH_COMPANY>' --env 'FREEMATICA_AUTH_ORGANIZATION=<FREEMATICA_AUTH_ORGANIZATION>' mcp-freematica -- npx -y @nubiia/mcp-freematica in your terminal. Add --scope user to make it available in every project.
How do I add Freemática MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Freemática MCP provide?
It exposes 66 tools, including freematica_list_articulos, freematica_get_articulo, freematica_get_precio_articulo, freematica_list_materiales_asignados_servicios, freematica_get_master_data.
Can I access customer and contact information?
Yes, you can list paginated customers, get specific customer details, and list customer contacts.
Does it support accounting exports?
Yes, the server can export accounting entries for a specific period in CSV or JSON formats.