jp-payroll-mcp

Nómina japonesa, seguro social y derecho laboral, calculados en lugar de consultados: primas para las 47 prefecturas, retención de impuestos, decisiones y revisiones de remuneración estándar, exenciones de permisos, salario mínimo, con el estatuto o aviso ministerial en el que se basa cada respuesta.

Verificado contra las tablas publicadas celda por celda: 3,638 aserciones en cada cambio.

Dos formas de acceso

Como servidor MCP, para hacer preguntas a través de un asistente de IA. 17 herramientas, gratis, sin clave:

claude mcp add jp-payroll -- npx -y jp-payroll-mcp

Como API HTTP, para integrarlo en software. 36 endpoints, OpenAPI 3.0, lote:

curl "https://japan-payroll-api.tsumugi.workers.dev/v1/payroll?prefecture=Tokyo&monthly_salary=350000&birth_date=1986-04-01"

El servidor MCP es una capa delgada sobre la API, por lo que ambos dan las mismas respuestas. Cuál quieras depende de si pregunta una persona o un programa.

• Código fuente del servidor MCP y su propio README: mcp/ · 日本語

• API en vivo: https://japan-payroll-api.tsumugi.workers.dev

• Especificación OpenAPI: /openapi.json

Related MCP server: taiwan-payroll

Herramientas relacionadas

Los servidores MCP estatutarios japoneses en su mayoría recuperan: te entregan el texto de una ley y te dejan el razonamiento a ti. Este calcula y devuelve la disposición en la que se basó. Se complementan en lugar de competir:

Si ya ejecutas uno de esos, añade este junto a él. Un asistente con ambos elige el correcto según la pregunta.

Por qué existe esto

• No existe una API consolidada. Los desarrolladores ensamblan esto a partir de 協会けんぽ, 厚生労働省 y cada oficina laboral de prefectura por separado.

• Las reglas son complicadas. Las primas se calculan sobre la remuneración mensual estándar (una función escalonada de 50 grados), no sobre el salario real, excepto el seguro de empleo, que usa el salario real. La pensión tiene un tope en el grado 32. El cuidado a largo plazo se aplica solo a edades de 40 a 64. La parte del empleado se redondea hacia abajo (≤ 0,50 yenes se trunca). Equivocarse en uno de estos produce números que parecen plausibles y son incorrectos.

Servidor MCP

Código fuente en mcp/, con su propio README · 日本語. Pruébalo con npm run mcp:test: utiliza un transporte stdio real con el cliente MCP real, porque una herramienta con un manejador roto aún se lista perfectamente y solo falla cuando algo la llama.

El servidor MCP es gratuito y siempre lo será. Es un canal de distribución más que de ingresos: npm no paga nada y MCP no tiene facturación propia. Esto es deliberado: el problema nunca fue la facturación, que RapidAPI ya maneja, sino el descubrimiento, y MCP es donde está mediblemente el tráfico de datos estatutarios japoneses.

Endpoints

prefecture acepta un nombre en inglés (Tokyo, sin distinción de mayúsculas), japonés (東京 o 東京都) o un código JIS (13).

La única llamada que importa

Ejecutar la nómina de un empleado es una sola solicitud:

curl "https://japan-payroll-api.tsumugi.workers.dev/v1/payroll?prefecture=Tokyo&monthly_salary=350000&age=40&dependants=2"

gross                    350,000
social insurance          -55,750
                       ----------
after social insurance   294,250   <- the base withholding tax is charged on
withholding income tax    -4,480
                       ----------
net pay                  289,770

Esa línea intermedia es el punto clave. El impuesto sobre la renta se aplica sobre el salario después del seguro social, no sobre el salario bruto, y calcularlo a mano es el error que este endpoint existe para evitar. La respuesta también incluye el tramo que se resolvió, cada prima desglosada en parte del empleado y parte del empleador, y qué tramo produjo el impuesto, de modo que la aritmética pueda auditarse en lugar de darse por sentada.

El impuesto de residente (住民税) lo evalúa el municipio y se notifica al empleador; ninguna API puede calcularlo. Pasa resident_tax= y se restará del salario neto.

Pasa income_tax=false para obtener solo el seguro social.

Antes de integrar

• GET /v1/enums enumera todos los valores aceptados — business_type, column, calendar — y todos los códigos de error, para que puedan leerse en tiempo de compilación en lugar de descubrirse con un 400.

• Los errores llevan un code estable. invalid_request y missing_parameter significan que hay que corregir la llamada; out_of_coverage significa que la entrada era válida pero queda fuera de lo publicado, lo que requiere una rama distinta. No te bases en el texto en inglés — cambiará.

• GET /v1/data-freshness te indica cuán actualizado está cada conjunto de datos.

Datos

Todas las cifras se extraen programáticamente de las hojas de cálculo oficiales — no se transcriben a mano. Consulta scripts/ para los extractores.

Por qué no la ley

Las cifras del impuesto sobre la renta provienen de las tablas publicadas por la Agencia Tributaria Nacional en lugar de la 所得税法 a través de la API de leyes e-Gov, porque la versión legal omite el recargo de reconstrucción del 2,1%. Entre 105.000 y 107.000 yenes, la columna 乙 es de 3.700 yenes en 別表第二 y de 3.800 yenes en la práctica; por debajo de 105.000 yenes es del 3% en lugar del 3,063%. La ley es la fuente equivocada para la nómina.

Por encima de 740.000 yenes, la tabla deja de ser una tabla: se convierte en puntos de anclaje con un tipo marginal. Esas anclas no son colineales — el redondeo está incorporado en cada una —, así que se conservan los valores de anclaje publicados en lugar de recalcularlos. La columna 乙 solo tiene dos anclas (740.000 y 1.710.000) donde 甲 tiene nueve, y medir el exceso de 乙 desde una ancla de 甲 cobra de menos en silencio. Ese fue un error real aquí, detectado por la comparación celda por celda.

Las citas se resuelven a texto

Nombrar una ley y dejar que el lector la busque es media respuesta. Cada disposición que cita esta API está incluida, de modo que 健康保険法第43条 puede convertirse en sus palabras reales en la misma operación:

curl 'https://japan-payroll-api.tsumugi.workers.dev/v1/statute?ref=健康保険法第43条'
curl '…/v1/standard-remuneration/revision?…&include=statute_text'

Las citas se escriben de muchas maneras en la práctica y todas se resuelven — 健保法43条, 厚年法81条の2, 徴収法11条, un 第 omitido, referencias a nivel de párrafo, dígitos de ancho completo. Las abreviaturas de e-Gov no son las que usan los profesionales (e-Gov la llama 厚生年金法; todo el mundo escribe 厚年法), así que se aceptan ambas.

El texto proviene de la API 法令API de e-Gov en tiempo de compilación en lugar de en tiempo de solicitud: llamar a e-Gov en cada solicitud significaría que esta API se cae cuando la de ellos se cae.

scripts/extract-statutes.py contiene la única lista de disposiciones, y el conjunto de pruebas comprueba que toda cita que el código emite se resuelve — una cita añadida sin una disposición que la respalde hace fallar la compilación en lugar de devolver silenciosamente nada.

Limitaciones conocidas

• Las tablas del ajuste de fin de año no están incluidas. El 「給与所得控除後の給与等の金額の表」 de 令和8年分 aún no se había publicado a fecha de 2026-08; la Agencia Tributaria lo publica alrededor de septiembre. La 令和8年度税制改正 también eleva la deducción mínima por ingresos del trabajo a 740.000 yenes con efecto desde 2026-12-01, así que esa tabla también cambia.

• El salario mínimo de FY2026 no está incluido. A fecha de 2026-08, las revisiones se seguían emitiendo prefectura por prefectura y entran en vigor desde octubre de 2026. La API sirve el de FY2025, que es el tipo actualmente en vigor. Esto debe actualizarse una vez que las 47 prefecturas publiquen.

• El historial del seguro de empleo es solo FY2026. Los años anteriores no se verificaron contra una fuente primaria, así que se omiten en lugar de adivinarse.

• El impuesto de residente queda fuera del alcance. Depende de los ingresos del año anterior y del municipio, y lo recauda el municipio en lugar de calcularlo el empleador, así que /v1/payroll deduce la cifra que pases y nunca deriva una.

• Los endpoints de juicio deciden si una declaración es obligatoria; no son la declaración. Varias reglas dependen de hechos que una API no puede ver — si una variación estacional es 「業務の性質上例年発生することが見込まれる」, si una asignación es 実費弁償, si el empleado dio su consentimiento. Esos son insumos declarados, reflejados en la respuesta, y el asegurador puede llegar a una conclusión diferente bajo 保険者算定.

• No todas las vías de remuneración estándar están cubiertas. 資格取得時決定 devuelve cuánto tiempo permanece en vigor la decisión pero no calcula el 報酬月額 inicial (健保法42条1項 tiene cuatro métodos, tres de los cuales necesitan cifras sobre otros empleados). 二以上事業所勤務 — donde se suman las remuneraciones de varios empleadores y la prima se divide entre ellos — no está implementado en absoluto. Tampoco el re-anclaje que ocurre cuando el salario fijo cambia dos veces dentro de la ventana de tres meses.

• Algunos puntos de práctica no pudieron atribuirse a un documento primario y se enumeran como guidance.fixed_pay.unverified en la respuesta en lugar de afirmarse: si 家族手当 cuenta como salario fijo, cómo se cuenta la licencia pagada hacia 支払基礎日数, y cómo se trata 年俸制. Las fuentes secundarias coinciden en los tres; los ministerios no parecen decirlo por escrito.

Verificación

test/verify.mjs ejecuta 3.638 aserciones contra un servidor en vivo. El núcleo compara las primas calculadas por la API con los importes impresos en el libro de trabajo oficial de 協会けんぽ para 250 combinaciones de prefectura × tramo — las cifras publicadas de la parte del empleado, no una reimplementación de la fórmula. También comprueba:

• la contigüidad de los límites de tramo, y que un valor de yen en el límite pertenece al tramo superior

• el límite de pensión en los tramos 1 y 32

• el seguro de cuidados de larga duración que se activa a los 40 y se desactiva a los 65

• el seguro de empleo que se aplica sobre el salario real mientras que otras primas usan el tramo

• el salario mínimo en un punto temporal (incluido el día anterior a una fecha de entrada en vigor)

• la resolución de prefectura en las cuatro formas de entrada

• las 47 prefecturas devolviendo una respuesta de nómina válida

• los recuentos de días hábiles contra una referencia calculada de forma independiente

• el 2026-09-22 国民の休日 (un festivo solo porque se sitúa entre otros dos)

• los festivos imperiales puntuales: 大喪の礼, 即位礼正殿の儀, 結婚の儀

• el dígito de control del número corporativo contra el ejemplo resuelto en el PDF de la NTA, y que cualquier otro dígito de control se rechaza para la misma base

• cada celda publicada de la tabla de retención en origen — 231 tramos × 8 columnas de 甲 más la columna 乙, 2.079 cifras, comparadas con el propio libro de trabajo de la Agencia Tributaria Nacional

• que un dígito de control de factura válido no se atribuye a una corporación: los autónomos cumplen la misma regla, así que el titular no puede inferirse del número

• los ocho casos de 随時改定 de un solo tramo que publica 日本年金機構 — cuatro para salud, cuatro para pensión —, cada uno aterrizando en la remuneración estándar que nombra la tabla, tanto en el tramo real como en la escala extendida que usa la implementación

• que la salud y la pensión se juzgan de forma independiente: una subida por encima del techo de pensión mueve seis tramos de salud y ningún tramo de pensión

• el respaldo de 定時決定 de 15 días que se activa para 短時間就労者 y no para nadie más, y no en 随時改定 en ningún momento

• que cada conjunto cerrado de valores aparece en /v1/enums, de modo que un nuevo enum no puede publicarse sin llegar al endpoint del que los integradores generan sus tipos

npx wrangler dev --port 8799
node test/verify.mjs

# or against production
BASE=https://japan-payroll-api.tsumugi.workers.dev node test/verify.mjs

Desarrollo / despliegue

npm install
npx wrangler dev
npx wrangler deploy

Los datos están incrustados en el bundle (~40 KB comprimidos con gzip), así que no hay base de datos, ni KV, ni arranque en frío.

Las respuestas llevan Cache-Control: public, max-age=3600, stale-while-revalidate=86400. Una hora en lugar de un día, porque los tipos cambian en fechas conocidas y una corrección debería llegar a los llamadores el mismo día; stale-while-revalidate mantiene las respuestas instantáneas mientras la actualización ocurre detrás. Ten en cuenta que las respuestas de workers.dev no se almacenan en caché en el propio edge de Cloudflare — cada solicitud invoca el Worker. Un dominio personalizado habilitaría el almacenamiento en caché en el edge si eso merece la pena.

Medido desde Japón contra el Worker desplegado: mediana de 65 ms, máximo de 83 ms de ida y vuelta; gzip reduce la tabla de 50 tramos de 6.841 a 1.041 bytes.

Mantenimiento

Las cifras legales cambian en fechas fijas, y una API que se pierde una revisión sigue respondiendo — con números que dejaron de ser ciertos. Dos mecanismos protegen contra eso.

La API informa de su propio desfase. GET /v1/data-freshness indica qué cubre cada conjunto de datos y cuándo debe cambiar a continuación, y las respuestas principales de datos llevan un marcador freshness. Un llamador puede ver una cifra desfasada incluso si nuestra monitorización falló.

Un trabajo semanal vigila las fuentes.

npm run watch          # fingerprints each source, alerts Discord on change
npm run watch:dry      # same, without notifying

Comprueba dos cosas independientes, porque cualquiera de las dos sola deja un hueco: el hash del archivo fuente y Last-Modified (detecta una reemisión silenciosa), y el calendario (detecta el caso en que un ministerio publica la revisión en una URL nueva y deja la antigua intacta).

Una alerta lleva los comandos exactos para ese conjunto de datos en lugar de apuntar de vuelta aquí. La alerta se lee meses después, normalmente por alguien que ha olvidado la estructura de este repositorio.

Ensaya un extractor antes de necesitarlo. El extractor de salario mínimo acepta --check, que ejecuta la extracción completa y la compara con los datos actualmente publicados en lugar de escribir nada:

curl -L -A "Mozilla/5.0" -o mw.xlsx https://www.mhlw.go.jp/content/11200000/001571219.xlsx
python scripts/extract-minimum-wage.py --check

Debería decir que la salida coincide. Si no lo hace mientras el año fiscal no ha cambiado, el extractor y los datos publicados han divergido — lo cual conviene saber en agosto en lugar de descubrirlo el día en que llegan las nuevas cifras, cuando la tentación es publicar lo que sea que produzca el script.

Regístralo para que se ejecute semanalmente:

powershell -ExecutionPolicy Bypass -File scripts
egister_watch_task.ps1

Verificar la vía de pago

El conjunto de pruebas no puede comprobar que los planes de pago de RapidAPI obtienen lotes de tamaño completo: hacerlo requiere el secreto de proxy que emite RapidAPI, y un secreto que vive en una prueba no es un secreto. Comprueba la mitad que importa para los ingresos — que un llamador sin el secreto no puede reclamar un plan de pago estableciendo una cabecera.

Confirma la otra mitad desde los registros después de cualquier cambio en los derechos de acceso:

npx wrangler tail --format json

Llama a cualquier endpoint desde el playground de RapidAPI y busca la línea de solicitud. Debería incluir el nombre de la suscripción:

{"channel":"rapidapi","path":"/","status":200,"plan":"BASIC"}

La presencia de plan significa que el secreto del proxy coincide. plan: null en una solicitud rapidapi significa que no coincide — y cada cliente de pago está recibiendo los límites del plan gratuito mientras se le cobra. Ese fallo es silencioso desde fuera, por lo que merece la pena una comprobación deliberada en lugar de esperar a una queja.

Las fechas que importan

Después de actualizar cualquier conjunto de datos, actualiza src/data/freshness.json y ejecuta npm run rapidapi:prepare para que la API en vivo se vuelva a verificar y se regenere la especificación OpenAPI.

Proceso de publicación

Cada API es una receta en recipes/<slug>/recipe.py — los endpoints se declaran una sola vez allí, y tanto la especificación OpenAPI como el texto del listado de RapidAPI se generan a partir de ella.

npm run rapidapi:prepare

Ese comando, para cada receta:

1. valida la receta,

2. llama a todos los endpoints declarados en la API en vivo y exige un 200 con JSON analizable — y para los endpoints con parámetros obligatorios, exige un 400 cuando se omiten. Esto es lo que detecta la desviación entre recipe.py y src/index.ts,

3. escribe build/openapi/<slug>.openapi.json,

4. envía una notificación de Discord con la URL del listado, la ruta de la especificación y los valores exactos para pegar.

El listado en sí es manual. El formulario Add-API en https://rapidapi.com/provider/<id>/new está protegido por reCAPTCHA v3, por lo que el envío final lo hace una persona — tres campos, elige "Specify using: OpenAPI", sube la especificación generada. Aproximadamente dos minutos por API, lo que no supone un cuello de botella para un ritmo de una o dos por semana.

Configura DISCORD_WEBHOOK_URL en .env (consulta .env.example) para que la notificación llegue realmente; sin él, el mensaje solo se imprime en la consola.

Sesión del navegador

npm run rapidapi:login abre una ventana real de Chrome para que inicies sesión manualmente — el script nunca ve la contraseña. La sesión persiste en rapidapi_profile/ (ignorado por git). Vuelve a ejecutarlo cuando la sesión caduque.

Seguridad operativa

• state/pipeline.halt.json detiene todo hasta que una persona lo elimina. set_halt() se llama cuando una sesión muere; clear_halt() al volver a iniciar sesión correctamente.

• MAX_PUBLISH_PER_DAY / MIN_SECONDS_BETWEEN_PUBLISH en pipeline/rapidapi/config.py mantienen un ritmo humano.

Licencia y atribución

Los datos subyacentes son datos abiertos del gobierno japonés bajo la 公共データ利用規約(第1.0版), que permite el uso comercial y la redistribución con atribución. Cada respuesta incluye un bloque attribution que nombra la fuente.

Este servicio no está respaldado por ninguna agencia del gobierno japonés. Verifica contra la fuente oficial antes de confiar en él para presentaciones legales.