nts-tax-mcp

Servidor MCP (Model Context Protocol) que permite buscar directamente desde Claude en el Sistema de Información de la Legislación Tributaria Nacional (taxlaw.nts.go.kr) y el Sistema de Información de la Legislación Tributaria Local (olta.re.kr).

Impuestos nacionales: Respuestas previas · Consultas escritas · Respuestas a consultas (Servicio de Impuestos Nacionales / Ministerio de Economía y Finanzas / Ministerio de Legislación), Apelaciones al Tribunal de Arbitraje Tributario, Apelaciones al Servicio de Impuestos Nacionales, Jurisprudencia judicial, Legislación

Impuestos locales (añadido en v3): Decisiones del Tribunal de Arbitraje Tributario relacionadas con impuesto de adquisición · impuesto predial · impuesto automotriz · impuesto sobre la renta local · impuesto de registro y licencia, Decisiones de la Junta de Auditoría, Decisiones del Tribunal Constitucional, Jurisprudencia judicial, Interpretaciones autorizadas del Ministerio de Legislación / Ministerio de Seguridad y Administración Pública, Respuestas a consultas de gobiernos locales

Ampliación de información legislativa (v5, añadido en la versión extendida server_ext.py): Basado en la API abierta del Centro Nacional de Información Legislativa (law.go.kr), permite buscar jurisprudencia del Tribunal Supremo y tribunales inferiores, historial legislativo y artículos en una fecha específica, interpretaciones legislativas, reglamentos administrativos (reglas básicas, etc.), tratados fiscales y normativa autónoma (ordenanzas) con un solo conector.

v5 — Migración a servidor propio + 8 herramientas de law.go.kr añadidas (2026-08)

Debido al agotamiento de créditos de Railway, el servidor cayó (2026-08-08) y se migró a un servidor propio en funcionamiento continuo + exposición mediante Tailscale Funnel (completado el 2026-08-09). Durante la migración, se añadieron 8 herramientas de la API abierta de law.go.kr, ampliando el conector a un total de 14 herramientas.

• Punto de entrada extendido: server_ext.py — hereda las 6 herramientas existentes de server.py (impuestos nacionales/locales) mediante from server import mcp y registra 8 herramientas adicionales de law.go.kr a través del cliente law_go_kr.py. server.py no se modifica, por lo que si solo se necesitan las 6 herramientas originales, se puede ejecutar server.py directamente.

• 8 nuevas herramientas: court_case_search/court_case_detail (jurisprudencia de law.go.kr), law_interpretation_search (interpretaciones legislativas), law_history_search (lista de versiones históricas de leyes), law_article_as_of (texto de un artículo en una fecha específica — para verificar el artículo citado en reglamentos o jurisprudencia), admin_rule_search (reglamentos administrativos — reglas básicas, reglamentos de procedimiento de investigación, avisos), treaty_search (texto de tratados fiscales y fecha de entrada en vigor), ordinance_search (normativa autónoma — ordenanzas de reducción de impuestos locales, etc.)

• Requisito previo: La API abierta de law.go.kr solo funciona desde IP registradas. Se debe registrar la IP pública del servidor en open.law.go.kr → Solicitudes de API abierta. Si no está registrada, las 8 herramientas de law.go.kr mostrarán "error de autenticación", mientras que las 6 herramientas originales de impuestos nacionales/locales funcionarán normalmente. La variable de entorno LAW_API_OC (código de institución emitido al registrarse en law.go.kr, obligatorio) especifica la cuenta de autenticación. Como es información de identificación personal, no se incluye el valor real en este repositorio, sino que se carga desde un archivo local .gitignore que solo está en el servidor.

• Modo de operación actual: En el servidor, run_server.bat (puerto 8734, ejecuta server_ext.py) se ejecuta continuamente mediante el Programador de tareas de Windows (nts-tax-mcp, ejecución automática con permisos SYSTEM al inicio), y se expone externamente con tailscale funnel --bg 8734 en la dirección fija https://desktop-ika1349.tail81ecba.ts.net/mcp. La instalación inicial se completa con una sola ejecución de setup.ps1 (descarga de fuente desde GitHub → instalación de dependencias → registro en el Programador de tareas, todo automatizado).

Related MCP server: LexGuard MCP

v5.1 — Corrección de error de análisis de artículos + indicación de truncamiento (2026-08-16)

• Corrección de error de análisis del primer artículo de una sección: Se corrigió un error por el cual law_article_as_of devolvía solo el título de la sección (ej. "제6절 …") en lugar del texto del artículo cuando se consultaban artículos que iniciaban una sección, subsección o capítulo (ej. artículos 104 y 55 de la Ley del Impuesto sobre la Renta). La causa era que el nodo del título aparecía primero con el mismo <조문번호> que el artículo real; ahora se filtran los bloques de título que no contienen el texto del artículo.

• Indicación de truncamiento + exposición de max_chars: Cuando un artículo supera max_chars (por defecto 6000 caracteres), anteriormente se truncaba la parte final (últimos párrafos) sin indicación. Ahora, si se trunca, la respuesta incluye un elemento "잘림" con la longitud total y cómo volver a consultar, y se ha añadido el parámetro max_chars a la herramienta law_article_as_of para obtener el texto completo.

• Precaución operativa — .bat debe tener saltos de línea CRLF: Si run_server.bat se guarda con saltos de línea LF, cmd.exe saltará líneas, ignorando la configuración PORT=8734 y el servidor se iniciará en el puerto predeterminado 8000 (caso real de fallo — Funnel apunta al 8734, por lo que el conector queda inoperativo). Dependiendo del editor, los saltos de línea pueden cambiarse a LF al guardar; después de modificar .bat, verifique que sea CRLF.

v5.2 — Consulta de artículos individuales de reglamentos administrativos (2026-08-17)

Se añadieron los parámetros article (número de artículo), max_chars y start_char a admin_rule_search. Para avisos grandes como el Reglamento de Transacciones de Divisas (aviso del Ministerio de Economía y Finanzas, aproximadamente 300,000 caracteres), antes solo se podían ver los primeros 10,000 caracteres. Ahora, especificando el número de artículo, se obtiene solo ese artículo — ej.: para la declaración de inversión directa en el extranjero, serial=número de serie del Reglamento de Transacciones de Divisas, article="9-5" (Artículo 9-5). Si no se conoce el número de artículo, se puede leer secuencialmente con el desplazamiento start_char, y si se trunca, el elemento "잘림" en la respuesta indica cómo consultar a continuación.

Mejora de velocidad (2026-08-18): Se almacena en caché la respuesta de law.go.kr durante 10 minutos, por lo que al consultar artículos consecutivos de la misma ley no se vuelve a descargar el XML completo de la ley (ej. Ley del Impuesto sobre la Renta, 610,000 caracteres) (el segundo artículo se devuelve inmediatamente). También se corrigió un error en el parámetro de tamaño de página de la consulta de historial (numOfRows→display), reduciendo los viajes HTTP de 5 a 1 (medido: consulta en frío de 1 artículo de 1.1 s a 0.6 s).

v3 — Adición del Sistema de Información de la Legislación Tributaria Local (olta.re.kr)

Los impuestos nacionales y locales tienen sistemas de numeración de casos diferentes en el Tribunal de Arbitraje Tributario.

• Nacionales: 조심-YYYY-código de oficina regional-NNNN (ej. 조심-2023-서-9465)

• Locales: 조심YYYY지NNNN (ej. 조심2026지0284)

En la práctica, al buscar con la misma palabra clave en ambos sistemas, las decisiones del Tribunal de Arbitraje Tributario casi no se superponen (el sistema del Servicio de Impuestos Nacionales no indexa casos locales). No obstante, por seguridad, la herramienta nts_and_olta_precedent_search normaliza los números de documento, elimina duplicados e informa del número de duplicados eliminados (duplicates_removed).

Estructura de archivos

nts-tax-mcp/
├── server.py                    # MCP 서버 본체 (FastMCP) — 기본 도구 6개 (국세+지방세)
├── server_ext.py                # 확장 진입점 — server.py 6개 + 법제처 8개 = 14개 도구
├── nts_tax_ruling_search.py     # 국세: taxlaw.nts.go.kr 검색 클라이언트
├── olta_tax_ruling_search.py    # 지방세: olta.re.kr 검색 클라이언트
├── law_go_kr.py                 # 법령정보: law.go.kr Open API 클라이언트 (판례/법령/해석례/행정규칙/조약/자치법규)
├── test_mcp_client.py           # 서버 상태 독립 점검 스크립트
├── client/                      # MCP 커넥터 우회 독립 클라이언트 (CLI 포함)
│   ├── nts_client.py
│   ├── nts_search.py
│   └── README.md
├── requirements.txt
├── Procfile                     # Railway 배포용 (레거시 — 현재 운영은 서버컴퓨터+Tailscale Funnel)
├── setup.ps1                    # 서버컴퓨터 최초 설치 스크립트 (소스 다운로드→의존성→작업 스케줄러 등록)
├── run_server.bat               # 확장판(server_ext.py) 상시 구동용 — 작업 스케줄러가 부팅 시 실행
└── local_env.bat                # (커밋 안 됨) LAW_API_OC 등 개인 식별정보 — .gitignore 처리, 서버컴퓨터에서 직접 생성

Herramientas proporcionadas

server.py expone 6 herramientas básicas; server_ext.py expone 6 básicas + 8 de law.go.kr = 14 herramientas en total. El servidor de producción real (servidor propio) ejecuta server_ext.py, por lo que las 14 herramientas están disponibles.

6 básicas (impuestos nacionales/locales, server.py)

8 extendidas (law.go.kr, solo añadidas en server_ext.py)

v4 — Funcionalidad de búsqueda avanzada (reflejo completo de candidatos a mejora)

• Paginación, período y ordenación en OLTA: olta_collection_search permite explorar en profundidad una categoría específica en lotes de 10. El período (YYYYMMDD) y la ordenación por fecha más reciente se procesan del lado del servidor, por lo que son precisos.

• Consulta de texto completo en OLTA: olta_get_detail obtiene el texto completo de las decisiones del Tribunal de Arbitraje Tributario y del Tribunal Constitucional (resumen de la decisión, descripción de la sanción, juicio).

• Filtro de impuesto del lado del servidor en NTS: Si se proporciona un nombre de impuesto exacto en tax_type_filter (14 tipos: impuesto sobre ganancias de capital, impuesto de sociedades, IVA, impuesto sobre sucesiones y donaciones, impuesto sobre bienes inmuebles globales, etc.), se aplica automáticamente un filtro de código del lado del servidor, filtrando con precisión sobre el conjunto completo de datos.

Para especificaciones detalladas de datos y tabla de códigos, consulte DATA_SOURCES.md.

v2.1 Corrección de errores (importante)

Se corrigieron problemas encontrados durante el trabajo en la carpeta client/.

• Problema donde el filtro de fecha (date_from/date_to) rompía la búsqueda — La pantalla de búsqueda integrada de taxlaw.nts.go.kr no tiene una interfaz de filtro de período, por lo que los parámetros bltnStrtDtm/bltnEndDtm añadidos por conjetura en versiones anteriores se trataban como valores incorrectos, dando como resultado 0 resultados de búsqueda. Se eliminaron esos parámetros y se reemplazaron por un filtro del lado del cliente que filtra por el campo date después de recibir los resultados.

• También se corrigió un problema donde los marcadores de resaltado de búsqueda (<!HS>, <!HE>) no se eliminaban del campo doc_no, lo que impedía la coincidencia exacta en nts_ruling_get_by_doc_no.

Cliente independiente para evitar el conector MCP (client/)

Cuando la conexión del conector de Claude es inestable, se puede acceder directamente al servidor sin pasar por MCP mediante un cliente independiente añadido en la carpeta client/. Consulte client/README.md para su uso.

cd client
python nts_search.py --ping
python nts_search.py "조정대상지역" -c precedent -n 10

v2 Mejoras

Desde la versión inicial, se han mejorado los siguientes aspectos.

1. Verificación de ejecución local

pip install -r requirements.txt
python server.py

Por defecto, el servicio se ofrece en http://0.0.0.0:8000/mcp mediante streamable-http. El puerto se puede cambiar con la variable de entorno PORT.

PORT=8765 python server.py

Opciones de variables de entorno

2. Despliegue

2-A. Modo de operación actual — Servidor propio en funcionamiento continuo + Tailscale Funnel (2026-08~)

Después de que el servidor cayera por agotamiento de créditos de Railway (2026-08-08), se migró a un servidor propio en funcionamiento continuo. Las 14 herramientas (server_ext.py) se operan de esta manera.

1. Ejecutar setup.ps1 una vez en PowerShell como administrador en el servidor — descarga la fuente desde GitHub, instala las dependencias, registra nts-tax-mcp en el Programador de tareas de Windows (ejecución automática con permisos SYSTEM al inicio) y lo inicia inmediatamente.

   Set-ExecutionPolicy -Scope Process Bypass -Force
   .\setup.ps1

2. run_server.bat establece PORT=8734 y ejecuta server_ext.py (registro: server.log). LAW_API_OC no se escribe directamente en este archivo, sino que se carga desde un archivo local .gitignore (local_env.bat — una línea set LAW_API_OC=su_código_de_institución). Si este archivo no existe, solo las 8 herramientas de law.go.kr no funcionarán; las 6 básicas funcionarán normalmente.

3. Instale Tailscale, inicie sesión y exponga el servidor externamente con una dirección fija mediante Funnel.

   tailscale funnel --bg 8734

4. URL real del servidor MCP (fija): https://desktop-ika1349.tail81ecba.ts.net/mcp

Si cambia el puerto, debe cambiar tanto PORT en run_server.bat como el puerto de destino en tailscale funnel. No reenvíe este puerto directamente en el enrutador; use solo Tailscale Funnel.

2-B. Despliegue en Railway (heredado)

Procfile sigue ejecutando python server.py, por lo que al desplegar en Railway solo estarán disponibles las 6 herramientas básicas, sin las 8 de law.go.kr (server_ext.py). Si se agotan los créditos, el servidor se detendrá, por lo que actualmente no se recomienda, pero sigue funcionando.

1. Suba esta carpeta a un repositorio de GitHub.

2. En Railway, seleccione "New Project" → "Deploy from GitHub repo".

3. Railway reconocerá Procfile y ejecutará automáticamente python server.py. (Railway inyecta automáticamente la variable de entorno PORT).

4. Una vez finalizado el despliegue, la URL real del servidor MCP será la dirección emitida por Railway seguida de /mcp.

3. Registro como conector en Claude

1. Acceda a claude.ai → Perfil → Configuración (Settings) → Conectores (Connectors)

2. Haga clic en "Añadir conector personalizado" (Add custom connector)

3. Nombre: el que desee (nombre actual del conector en producción: Korea nts)

4. URL: introduzca la dirección .../mcp obtenida en el paso 2 y guarde (dirección actual en producción: https://desktop-ika1349.tail81ecba.ts.net/mcp)

5. Establezca los permisos de la herramienta en "Permitir siempre" (el valor predeterminado "Requiere aprobación" pedirá aprobación cada vez)

6. Abra una ventana de chat completamente nueva y verifique que las herramientas aparezcan en la lista (inmediatamente después de activar el conector, es posible que no se refleje en las ventanas de chat ya abiertas)

4. Ejemplos de uso (en el chat de Claude)

• "Busca en el Centro de Información de la Legislación Tributaria Nacional respuestas a consultas y casos de apelación relacionados con áreas sujetas a ajuste"

• "Verifica si hay decisiones recientes del Tribunal de Arbitraje Tributario sobre la negación de cálculos de transacciones indebidas. Solo a partir de 2024."

• "Muéstrame el texto original del caso 조심-2023-서-9465" (consulta directa por número de caso)

• "Filtra solo el impuesto sobre ganancias de capital y muéstralo de nuevo" (filtro de impuesto)

• "Busca casos de apelación de impuestos locales relacionados con la sobretasa del impuesto de adquisición" (impuestos locales → olta_ruling_search)

• "Verifica si hay decisiones de la Junta de Auditoría relacionadas con la fecha base del impuesto predial" (impuestos locales → olta_ruling_search)

• "Busca todos los casos de apelación de impuestos nacionales y locales relacionados con áreas sujetas a ajuste, sin duplicados" (→ nts_and_olta_precedent_search)

• "Busca en las interpretaciones legislativas la palabra 'precio de liquidación'" (→ law_interpretation_search)

• "Muéstrame el historial del Decreto de la Ley del Impuesto sobre la Renta" (→ law_history_search)

• "Muéstrame el artículo 17 de la Ley del IVA, vigente el 15 de julio de 2008" (→ law_article_as_of)

• "Busca las reglas básicas de la Ley del Impuesto de Sociedades" (→ admin_rule_search)

• "Verifica la fecha de entrada en vigor del tratado fiscal Corea-Hong Kong" (→ treaty_search)

• "Busca la ordenanza de reducción del impuesto de adquisición de Seúl" (→ ordinance_search)

5. Verificación independiente del estado del servidor (sin Claude)

Cuando surja un problema con las herramientas en el chat de Claude, este script permite distinguir rápidamente si el problema es del servidor o de Claude. Envía solicitudes directamente al servidor mediante el protocolo MCP, sin pasar por Claude, verificando todo el flujo: initialize → tools/list → tools/call.

python test_mcp_client.py

El valor predeterminado del script es la dirección del antiguo servidor de Railway (https://web-production-10fe2.up.railway.app/mcp), pero Railway ya no está operativo debido al agotamiento de créditos (consulte 2-A). Para verificar el servidor actual en producción, asegúrese de especificar la dirección real con --url.

python test_mcp_client.py --url https://desktop-ika1349.tail81ecba.ts.net/mcp
python test_mcp_client.py --url http://127.0.0.1:8734/mcp

Si este script se ejecuta correctamente pero las herramientas no aparecen en el chat de Claude, la causa no es el servidor, sino un problema de reconocimiento/caché del conector de Claude. En ese caso, pruebe lo siguiente:

• Verifique de nuevo en una ventana de chat completamente nueva (es posible que no se refleje en las ventanas de chat existentes inmediatamente después de activar el conector)

• En Configuración → Conectores, elimine ese conector y vuelva a registrarlo

• Si aún no funciona, contacte a support.claude.com (podría ser un retraso en la actualización o un error en la plataforma de Claude)

Referencia de parámetros de herramientas

nts_ruling_search

nts_ruling_get_by_doc_no

olta_ruling_search (Impuestos locales)

nts_and_olta_precedent_search (Integrado nacional+local, eliminación de duplicados)

El valor de retorno incluye nts_precedent, olta_precedent, duplicates_removed (número real de duplicados eliminados).

olta_collection_search (Exploración profunda de impuestos locales)

olta_get_detail (Consulta de texto completo de impuestos locales)

Devuelve el texto completo del cuerpo, incluyendo resumen de la decisión, artículos de referencia, resumen de la disposición, juicio, etc.

court_case_search (Precedentes del Ministerio de Legislación, server_ext.py)

court_case_detail (server_ext.py)

law_interpretation_search (Casos de interpretación legal, server_ext.py)

law_history_search (Historial de leyes, server_ext.py)

law_article_as_of (Artículo en un momento específico, server_ext.py)

admin_rule_search (Reglas administrativas, server_ext.py)

treaty_search (Tratados fiscales, server_ext.py)

ordinance_search (Ordenanzas locales, server_ext.py)

Limitaciones conocidas (v5)

• Las 8 herramientas de 법제처 (law.go.kr) solo están disponibles cuando se ejecutan con server_ext.py. Si se ejecuta solo server.py, solo se muestran las 6 básicas.

• Lista blanca de IP de law.go.kr: si se llama desde una IP no registrada, las 8 herramientas devuelven un error de "autenticación fallida". Debe registrar primero la IP pública del servidor en open.law.go.kr → Historial de solicitudes de OpenAPI.

• Análisis XML de law.go.kr: la respuesta se procesa con un analizador ligero basado en expresiones regulares. Si la estructura de la respuesta de la API cambia (cambio de nombres de etiquetas, etc.), el análisis puede fallar.

• law_article_as_of: selecciona automáticamente la versión con la fecha de vigencia máxima dentro de la fecha de referencia entre las versiones históricas. Si hay varias leyes con el mismo nombre (ley principal, decreto de ejecución, reglamento), puede seleccionar una versión no deseada a menos que se especifique law_id.

• Filtro de tipo de impuesto de NTS: si se proporciona el nombre exacto del impuesto (14 tipos como 양도소득세, consulte la tabla de códigos en DATA_SOURCES.md), se aplica un filtro del lado del servidor; de lo contrario, se realiza un posprocesamiento del lado del cliente.

• Filtro de período de NTS: se ha confirmado (mediante medición) que la API de búsqueda integrada no tiene parámetros de período, por lo que date_from/date_to se manejan como filtros del lado del cliente. Es más estable usarlos junto con la ordenación por fecha descendente (sort=date_desc).

• Solicitud de revisión de la Auditoría (impuestos nacionales): no está incluida en el alcance de este servidor. (Las decisiones de la Auditoría sobre impuestos locales están cubiertas por olta_ruling_search / olta_collection_search).

• nts_ruling_get_by_doc_no: no se ha identificado una API de consulta detallada dedicada, por lo que está implementada utilizando el número de documento como término de búsqueda.

• Análisis HTML de OLTA: olta.re.kr responde en HTML, por lo que se analiza con BeautifulSoup. Si la estructura de la página cambia (nombres de clases como p.se_title, ul.search_out, etc.), el análisis puede fallar.

• olta_ruling_search (búsqueda integrada) solo devuelve 3 vistas previas por categoría. Si necesita más resultados, use olta_collection_search (10 resultados por página, compatible con paginación, período y ordenación).

• La consulta de texto completo de olta_get_detail solo admite el Tribunal Tributario y el Tribunal Constitucional. La jurisprudencia judicial no es compatible porque la URL detallada requiere dos parámetros; las interpretaciones autorizadas se reemplazan con un resumen.

• Respuestas a consultas de gobiernos locales: existen en la tabla de códigos interna de olta.re.kr, pero no se muestran en la pantalla de resultados de búsqueda integrada, por lo que actualmente no se pueden buscar.

• Eliminación de duplicados: se ha confirmado mediante medición que no se producen duplicados reales debido a que los sistemas de números de caso del Tribunal Tributario nacional y local son diferentes; la eliminación de duplicados basada en normalización en nts_and_olta_precedent_search es una medida de seguridad.