Buk MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Buk MCP show me the salary history for employee Ana Soto since 2024"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Buk MCP
Servidor MCP comunitario para conectar Buk Chile con ChatGPT, Dots y otros clientes MCP. Incluye el catálogo completo de la API oficial indicada abajo y herramientas para historial salarial, remuneraciones, costo de equipos y comparación con el IPC.
Cada empresa utiliza su propia URL de Buk y su propia API key. El proyecto se puede autoalojar; el modo OAuth permite que varias empresas conecten sus credenciales por separado a un mismo servidor. No necesitas una API key de OpenAI para ejecutar el adaptador.
Integración independiente, sin afiliación ni aprobación de Buk. Este repositorio contiene código y datos públicos del IPC; no contiene claves ni datos de empleados. Publicar el código no publica un servicio alojado ni lo instala automáticamente en ChatGPT o Todd.
Qué incluye
206 operaciones documentadas en el esquema oficial de Chile: 119 GET y 87 operaciones de escritura. El catálogo se genera del esquema, sin mantener manualmente una lista parcial de rutas.
Descubrimiento de operaciones, parámetros, permisos y esquemas de respuesta. Puedes consultar cualquier endpoint documentado a través de las herramientas genéricas.
Sueldo base histórico, aumentos, jornada, moneda y liquidaciones por período.
Costo mensual de equipos según la fórmula estándar de Buk, con aportes observados, desglose por persona, haberes fijos/ocasionales y comparación mensual.
Simulación de cambios del sueldo base sin modificar Buk.
Comparación del sueldo con la serie mensual empalmada del INE de Chile.
Paginación, validación de parámetros, límites de tamaño, timeout, reintentos de lectura y errores con permisos o cobertura incompleta explícitos.
Transporte stdio y Streamable HTTP. HTTP ofrece OAuth con PKCE para varias empresas, o bearer fijo para una instalación aislada.
Pruebas de protocolo MCP, API, cálculos, autenticación y separación de empresas; CI para Node 22 y 24.
Las escrituras están desactivadas por defecto y no están disponibles en OAuth compartido. Una instalación aislada puede habilitarlas explícitamente. La cobertura del catálogo no elimina los permisos de la API key ni las restricciones de módulos contratados.
Related MCP server: dk-mcp
Inicio rápido: cliente MCP local
Requisitos: Node.js 22 o superior y una API key de Buk. Para sueldos se requieren permisos de lectura de remuneraciones y acceso a información sensible.
git clone https://github.com/gmorande/buk-mcp.git
cd buk-mcp
npm ci
npm run buildEn la configuración del cliente MCP, agrega el proceso con una ruta absoluta. Sustituye los valores de ejemplo en un archivo privado del cliente:
{
"mcpServers": {
"buk": {
"command": "node",
"args": ["/ruta/absoluta/buk-mcp/dist/index.js", "stdio"],
"env": {
"BUK_TENANT_URL": "https://tuempresa.buk.cl",
"BUK_API_KEY": "TU_CLAVE_PRIVADA",
"BUK_COUNTRY": "chile",
"BUK_ALLOW_WRITES": "false"
}
}
}
}La clave va en la configuración privada o gestor de secretos. No debe aparecer en prompts, argumentos de herramientas, commits o issues.
También puedes preparar un .env a partir de .env.example y usar:
node --env-file=.env dist/index.js stdioEl proceso stdio se comunica con un cliente MCP mediante stdin/stdout; no es una consola interactiva de preguntas.
ChatGPT, Todd y un servicio para varias empresas
Para clientes cloud utiliza el modo HTTP con OAuth, detrás de HTTPS:
BUK_AUTH_MODE=oauth
PUBLIC_URL=https://mcp.tudominio.cl
HOST=127.0.0.1
PORT=3000
OAUTH_DATA_DIR=/var/lib/buk-mcp
OAUTH_MASTER_KEY=32_BYTES_ALEATORIOS_CODIFICADOS_EN_BASE64
OAUTH_REDIRECT_URIS=https://chatgpt.com/connector_platform/oauth_redirectnode --env-file=.env dist/index.js httpRegistra https://mcp.tudominio.cl/mcp como MCP personalizado con OAuth en el cliente. La página de conexión solicita la URL y la API key de esa empresa, las verifica y guarda la credencial cifrada. El token OAuth queda vinculado a esa conexión; cada solicitud usa su propio cliente Buk.
El operador del servicio puede acceder a los datos autorizados por esas claves: cada empresa debe elegir un operador de confianza o autoalojar. La implementación incluida usa un proceso y una réplica con almacenamiento cifrado persistente. La guía explica HTTPS, callbacks, rotación, revocación, límites y despliegue con Docker.
Guía completa: DEPLOYMENT.md. La conexión personalizada y la admisión en el catálogo público de ChatGPT son procesos distintos; el proyecto no afirma tener aprobación del catálogo.
Preguntas de ejemplo
Sustituye X por una persona y especifica el período cuando sea relevante. El asistente debe resolver la ficha correcta y aclarar nombres de equipo ambiguos. “Tech” es un ejemplo de área: cada empresa utiliza su propia estructura.
Estas son las preguntas que ejecuta la suite test:live. El informe de verificación distingue éxito, datos parciales y fallos; no contiene los resultados de RR.HH.
ID | Pregunta | Herramienta principal |
Q01 | Busca a X y dime si tiene más de una ficha. |
|
Q02 | Muéstrame las áreas y subáreas de la organización. |
|
Q03 | ¿Cuánto me costó mensualmente el equipo Tech en el último mes cerrado? Dame el total y el desglose por persona. |
|
Q04 | Separa los haberes fijos, ocasionales y aportes patronales del equipo Tech. |
|
Q05 | ¿Cómo cambió el costo de Tech frente al mes anterior y cuántas personas o fichas había en cada mes? |
|
Q06 | ¿Quiénes integraban Tech a una fecha determinada y cuánto sumaban sus sueldos base mensuales? |
|
Q07 | Si subo 5% los sueldos base de Tech, ¿cuánto aumenta mensualmente esa suma? |
|
Q08 | Dame la evolución histórica del sueldo de X, con las fechas y porcentajes de sus aumentos. |
|
Q09 | Compara la evolución del sueldo base de X con el IPC. ¿Ganó o perdió poder adquisitivo? |
|
Q10 | ¿Cuánto tuvo X de haberes brutos, descuentos y líquido en un mes determinado? |
|
Q11 | ¿Cuántos días de vacaciones tenía X a una fecha determinada, descontando las vacaciones futuras registradas? |
|
Q12 | ¿Qué empresas o razones sociales puede consultar esta conexión? |
|
La verificación comprueba las llamadas y los cálculos necesarios para responder. No es una promesa de que cualquier modelo responda correctamente a cualquier redacción ni una prueba de todos los endpoints contra producción.
Herramientas MCP
El servidor mantiene pocas herramientas y descubre el catálogo completo bajo demanda. No obliga al cliente a cargar 206 descripciones a la vez.
Herramienta | Función |
| Buscar operaciones por texto, módulo/tag y método; listar el catálogo con paginación. |
| Obtener parámetros, permisos y esquemas oficiales antes de una llamada. |
| Ejecutar cualquier GET documentado con validación y paginación. |
| Ejecutar operaciones de escritura; sólo aparece cuando el servidor aislado las habilita. |
| Encontrar personas y fichas, señalando coincidencias ambiguas. |
| Calcular remuneraciones y costo de un equipo para un mes; comparar períodos. |
| Consultar sueldo base histórico, liquidaciones y comparación opcional con IPC. |
| Sumar sueldo base vigente a una fecha y simular variaciones porcentuales. |
| Comparar dos sueldos en CLP con índices oficiales de dos meses. |
También ofrece los recursos buk://api/catalog, buk://schema/chile y buk://guide/payroll, más prompts para costo de equipo e historial salarial.
Ejemplo de llamada
Primero descubre y describe la operación; sus parámetros y formatos de fecha pueden variar.
{
"name": "buk_read",
"arguments": {
"operationId": "get_employees_id_jobs",
"path": { "id": "123" },
"paginate": true
}
}{
"name": "buk_team_payroll",
"arguments": {
"team": "Tech",
"month": "2026-09",
"compare_previous": true
}
}Los IDs de operación se derivan del método y la ruta. El catálogo del servidor es la autoridad; el ejemplo de ficha 123 es ficticio.
Cómo calcula sueldos y costos
Costo estándar Buk: total de haberes + aportes patronales observados − asignación familiar. El servidor verifica los componentes de la liquidación y su reconciliación. La ausencia de aportes no se transforma silenciosamente en cero. Los ítems informativos, como el saldo acumulado de una provisión, no se suman como gastos mensuales.
Costo contable personalizado: si la empresa usa otra definición, expense_accounts permite indicar las cuentas de gasto aprobadas. Suma débitos menos créditos de esas cuentas, evitando sumar pasivos o contrapartidas. El mapeo requiere validación de Finanzas. No se mezclan automáticamente los dos métodos.
Historia y pertenencia a equipos: usa trabajos con fechas efectivas para el mes consultado. Un cambio de área dentro del mes se señala como provisional; para una distribución exacta se necesitan los centros de costo correspondientes. La jerarquía de áreas puede ser la actual: si hubo una reorganización histórica, usa area_ids explícitos e include_descendants=false.
Sueldo vigente: la proyección de sueldo base excluye bonos, gratificaciones, aportes y otros componentes. El escenario de 5% representa ese aumento del sueldo base; no estima de forma implícita todas las cargas adicionales.
IPC: calcula (sueldo final / sueldo inicial) / (IPC final / IPC inicial) - 1, con meses coincidentes. Descarga la serie mensual empalmada del INE y conserva una copia pública fechada como respaldo. Si falta el mes solicitado, no inventa el dato. Usa los niveles publicados del índice; el redondeo puede producir pequeñas diferencias frente a una calculadora con precisión interna adicional.
Siempre separa monedas, sueldos base, bruto, descuentos, líquido y costo empresa. income_net es el líquido indicado por Buk, no una confirmación de transferencia bancaria. Costos de proveedores, contratistas o beneficios fuera de Buk requieren otra fuente.
Detalles, supuestos y límites: ANALYTICS.md.
Cobertura de la API
Fuente oficial: Swagger de Buk Chile, visible en apidocs. Snapshot: 23 de octubre de 2026.
Método | Operaciones |
GET | 119 |
POST | 46 |
PUT | 6 |
PATCH | 18 |
DELETE | 17 |
Total | 206 |
La cobertura significa que cada operación del esquema tiene un ID, descripción, esquema de entrada y un camino de ejecución. Los módulos o endpoints privados, de otros países, de otros productos Buk o ausentes del documento suministrado no se inventan ni se presentan como verificados.
El documento oficial contiene algunas inconsistencias y una referencia de respuesta sin definición. Las normalizaciones y la lista completa de rutas están en API_COVERAGE.md. El esquema original se conserva íntegro en schema/buk-chile.json.
Para actualizarlo:
npm run schema:update
npm run checkRevisa el diff antes de incorporar cambios del contrato. La actualización de esquema no ejecuta escrituras en Buk.
Pruebas
Verificación del 23 de octubre de 2026: las 12 preguntas del README pasaron con una cuenta real de Buk Chile, usando un cliente MCP por stdio. Se comprobaron consultas y conciliaciones matemáticas, exclusivamente en lectura. El informe anonimizado contiene los estados y comprobaciones. Los datos reales, la clave y la identidad del cliente no están incluidos.
npm ci
npm run checkLa suite local usa fixtures ficticios. Comprueba todos los esquemas, validación, paginación, formatos de solicitud, límites, reintentos, errores, matemáticas, OAuth/PKCE, revocación, aislamiento de empresas y llamadas MCP reales por transportes de prueba. GitHub Actions ejecuta estas pruebas sin credenciales Buk.
Para verificar las 12 preguntas con una cuenta autorizada, configura tu .env privado y ejecuta:
BUK_LIVE_TEAM=Tech BUK_LIVE_MONTH=2026-09 \
node --env-file=.env --import tsx scripts/live-test.tsPuedes definir BUK_LIVE_EMPLOYEE_ID y BUK_LIVE_START_MONTH. Por defecto, el script elige una ficha con historial accesible y usa el mes anterior. Si necesitas un informe, indica BUK_LIVE_REPORT=/ruta/informe.json; sólo escribe preguntas, estados, comprobaciones y códigos de limitación. No guarda respuestas de Buk. El script fuerza lectura y falla si el servidor expone una herramienta de escritura.
Si hay áreas activas e históricas con el mismo nombre, usa BUK_LIVE_TEAM con un nombre único de la jerarquía. Las herramientas devuelven candidatos cuando el nombre es ambiguo; no mezclan automáticamente áreas homónimas.
Un fallo de permisos, un período abierto o datos incompletos no se reportan como éxito. Las pruebas de escritura usan simulaciones; no alteran datos reales para comprobar el catálogo.
Seguridad y contribuciones
Consulta SECURITY.md. Antes de abrir un issue, elimina claves, dominios privados, nombres, RUT, montos y respuestas completas. Adjunta una reproducción con datos ficticios.
Las mejoras deben conservar la separación por empresa, la trazabilidad de cálculos y las señales de cobertura. Una nueva operación debe venir del esquema oficial; un nuevo cálculo financiero necesita una definición explícita y pruebas de los casos que podrían cambiar su resultado.
Licencia del código: MIT. Los esquemas y series públicas incluidos mantienen la atribución a Buk y al INE; la licencia del código no reemplaza sus condiciones de uso.
Available Tools
8 toolsbuk_compare_salary_to_cpiARead-onlyIdempotent
Compare two CLP salaries in exact months using official INE linked Chile CPI indices. Returns nominal change, real change, inflation-adjusted salary and monetary gap. No personal or salary data are transmitted to INE.
Inputs: end_month (required), start_month (required), final_salary (required), initial_salary (required), +1 more.
buk_describe_operationARead-onlyIdempotent
Return the official description, permissions, parameter schema and response schema of a Buk operation. Always check this before using a new operation.
Inputs: operationId (required).
buk_list_operationsARead-onlyIdempotent
Discover every operation in the official Buk Chile API. Search Spanish names, English paths or tags; then describe the exact operation before calling it. Does not request HR data.
Inputs: tag, limit, method, offset, +1 more.
buk_readARead-onlyIdempotent
Execute any documented GET operation against the authenticated Buk tenant. Covers all read endpoints, including employees, payroll, accounting, recruiting, vacations, documents and other licensed modules. Parameters are validated against the official schema. Returns original Buk data plus pagination completeness; permission errors are explicit.
Inputs: operationId (required), path, query, paginate.
buk_recurring_payrollARead-onlyIdempotent
Sum a team’s contractual base wages as of an explicit date, by currency, and simulate a percentage change. This is a base-wage run-rate, not total employer cost.
Inputs: as_of (required), team, area_ids, company_id, +2 more.
buk_salary_historyARead-onlyIdempotent
Get contractual base-wage history, salary changes and historical payroll for one exact ficha, optionally compared with official Chile INE CPI for the same endpoint months. Does not infer missing salary history.
Inputs: end_month (required), employee_id (required), start_month (required), compare_cpi, +1 more.
buk_search_employeesARead-onlyIdempotent
Find Buk employees by name, email, ficha ID or document. Returns a minimized directory and flags multiple matches; never guesses which person is intended.
Inputs: limit, query, status.
buk_team_payrollBRead-onlyIdempotent
Calculate a team’s monthly gross/net payroll, employee breakdown and prior-month change using historical jobs. Standard Buk employer cost is calculated from reconciled earning/contribution/family-allowance lines; custom Finance-approved expense accounts are also supported. Missing data remain explicit. Only closed payroll is included by default.
Inputs: month (required), team, area_ids, company_id, +8 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
The discovery trio (list/describe/read) has clear roles, and the payroll analytics tools are differentiated by cost basis, scope, and purpose. The main overlap is that buk_read can access any GET endpoint, including data also served by specialized tools like buk_search_employees and payroll helpers, so agents may occasionally hesitate between raw read and specialized analysis.
All tools use a consistent buk_ prefix and snake_case naming. Most follow a verb_noun pattern, but several are noun phrases (team_payroll, salary_history, recurring_payroll) and buk_read is a bare verb, creating minor convention drift.
Eight tools is well scoped for a Buk API wrapper with discovery, generic read access, and a few high-value payroll analytics helpers. Each tool appears to earn its place without an excessively broad or thin surface.
The server covers discovery and read access comprehensively via buk_read, plus useful payroll and CPI analytics. However, it is effectively read-only and lacks any create, update, or delete operations, which is a notable gap for an API integration surface.
Maintenance
Related MCP Connectors
Find, document and execute authenticated API calls across 1000+ apps via one MCP server
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
MLB Stats API MCP — official MLB statistics (keyless).
Query metrics, targets, entities, and team data in your Steep workspace via MCP.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables read-only access to Sleeper fantasy sports data, including users, leagues, rosters, matchups, transactions, drafts, players, trending activity, playoff brackets, traded picks, and sport state via MCP tools.18-
- FlicenseNot gradedqualityCmaintenanceEnables read-only access to DraftKings DFS lobby data, including slates, contests, salaries, and roster rules, via MCP.-
- AlicenseBqualityBmaintenanceEnables read-only access to BuzzerBeater's public API through MCP tools for retrieving team, player, match, market, national team, and other game data.29MIT
- AlicenseAqualityBmaintenanceEnables MCP clients to search and describe API routes, retrieve people, admissions, academics, and billing records, download exports, and optionally make changes against a school information system, read-only by default.6431 npmMIT