nts-tax-mcp

Это MCP-сервер (Model Context Protocol), который позволяет напрямую использовать в Claude интегрированный поиск по Системе налогового законодательства (taxlaw.nts.go.kr) + Системе местного налогового законодательства (olta.re.kr).

Государственные налоги: Предварительные ответы · Письменные запросы · Разъяснения по запросам (Налоговая служба/Министерство стратегии и финансов/Министерство законодательства), Апелляции в Налоговую палату, Апелляции в Налоговую службу, Судебные прецеденты, Законодательство

Местные налоги (добавлено в v3): Решения Налоговой палаты по налогу на приобретение · налогу на имущество · автомобильному налогу · местному подоходному налогу · регистрационному и лицензионному сбору, Решения Счетной палаты, Решения Конституционного суда, Судебные прецеденты, Официальные толкования Министерства законодательства/Министерства администрации и безопасности, Разъяснения по запросам местных органов власти

Расширение законодательной информации (v5, добавлено в расширенной версии server_ext.py): Поиск прецедентов Верховного суда и нижестоящих судов, истории законодательства и статей на определенную дату, примеров толкования законов, административных правил (включая основные общие правила), налоговых соглашений и местных нормативных актов (постановлений) на основе Open API Национального центра законодательной информации (law.go.kr) с помощью одного коннектора.

v5 — Перенос на серверный компьютер + добавление 8 инструментов Министерства законодательства (law.go.kr) (2026-08)

Из-за исчерпания кредитов Railway сервер перестал работать (2026-08-08). Произведен перенос на постоянно работающий собственный серверный компьютер + метод экспозиции Tailscale Funnel (завершено 2026-08-09). В ходе переноса были дополнительно подключены 8 инструментов Open API Министерства законодательства (law.go.kr), расширив возможности до использования в общей сложности 14 инструментов через один коннектор.

• Точка входа расширения: server_ext.py — наследует 6 инструментов (государственные/местные налоги) из существующего server.py через from server import mcp и регистрирует 8 дополнительных инструментов Министерства законодательства через клиент law_go_kr.py. Поскольку сам server.py не изменен, при необходимости только в 6 базовых инструментах можно запускать server.py как есть.

• 8 новых инструментов: court_case_search/court_case_detail (прецеденты Министерства законодательства), law_interpretation_search (примеры толкования законов), law_history_search (список версий истории законодательства), law_article_as_of (текст статьи, действовавшей на определенную дату — для проверки статей, цитируемых в постановлениях/прецедентах), admin_rule_search (административные правила — основные общие правила, правила обработки расследований, уведомления), treaty_search (текст налоговых соглашений/дата вступления в силу), ordinance_search (местные нормативные акты — постановления о льготах по местным налогам и т.д.)

• Предварительное условие: Open API law.go.kr работает только с зарегистрированных IP-адресов. Необходимо предварительно зарегистрировать публичный IP-адрес сервера на open.law.go.kr → История заявок OpenAPI. Если IP не зарегистрирован, 8 инструментов Министерства законодательства будут выдавать ошибку "Ошибка аутентификации", а 6 базовых инструментов по государственным/местным налогам будут работать нормально. Учетная запись аутентификации задается через переменную окружения LAW_API_OC (код организации, выдаваемый при регистрации на law.go.kr, обязателен). Поскольку это личная идентификационная информация, фактическое значение не фиксируется в этом репозитории, а загружается из локального файла, находящегося в .gitignore, который хранится только на серверном компьютере.

• Текущий метод работы: На серверном компьютере run_server.bat (порт 8734, запуск server_ext.py) постоянно работает через Планировщик задач Windows (nts-tax-mcp, автоматический запуск с правами SYSTEM при загрузке), а tailscale funnel --bg 8734 обеспечивает внешний доступ по фиксированному адресу https://desktop-ika1349.tail81ecba.ts.net/mcp. Первоначальная установка завершается однократным запуском setup.ps1 (автоматизация: загрузка исходного кода с GitHub → установка зависимостей → регистрация в Планировщике задач).

Related MCP server: LexGuard MCP

v5.1 — Исправление ошибки парсинга статей + указание на обрезание статей (2026-08-16)

• Исправление ошибки парсинга первой статьи раздела: Исправлена ошибка, из-за которой law_article_as_of при запросе статьи, с которой начинается раздел, подраздел или глава (например, ст. 104 или ст. 55 Закона о подоходном налоге), возвращал только заголовок вроде "Раздел 6 …" вместо текста самой статьи. Причина в структуре, где узел заголовка появляется раньше фактической статьи с тем же <НомерСтатьи>. Теперь строки с номерами статей отфильтровывают блоки заголовков, отсутствующие в тексте.

• Указание на обрезание статьи + раскрытие max_chars: Если статья превышает max_chars (по умолчанию 6000 символов), ранее хвостовая часть (последние пункты) обрезалась без каких-либо указаний. Теперь в случае обрезания в ответ добавляется пункт "Обрезано" с указанием общей длины и способа повторного запроса, а в инструмент law_article_as_of добавлен параметр max_chars для получения полного текста.

• Внимание к эксплуатации — .bat обязательно должен иметь разрывы строк CRLF: Если run_server.bat сохранен с разрывами строк LF, cmd.exe может пропускать строки, и настройка PORT=8734 будет проигнорирована, в результате чего сервер запустится на порту по умолчанию 8000 (реальный случай сбоя — Funnel смотрит на 8734, поэтому коннектор перестает работать). В зависимости от редактора разрывы строк при сохранении могут измениться на LF, поэтому после редактирования .bat обязательно проверьте, что они CRLF.

v5.2 — Поиск статей административных правил (2026-08-17)

В admin_rule_search добавлены параметры article (номер статьи), max_chars и start_char. Для крупных уведомлений, таких как Правила валютных операций (уведомление Министерства финансов и экономики, около 300 000 символов), возврат полного текста невозможен, поэтому ранее можно было увидеть только первые 10 000 символов. Теперь, указав номер статьи, можно получить только соответствующую статью — например, для уведомления о прямых зарубежных инвестициях: serial=серийный_номер_Правил_валютных_операций, article="9-5" (статья 9-5). Если номер статьи неизвестен, можно продолжить чтение со смещением start_char, а в случае обрезания пункт "Обрезано" в ответе укажет способ следующего запроса.

Улучшение скорости (2026-08-18): Кэширование ответов law.go.kr на 10 минут позволяет не загружать заново полный XML закона (например, Закон о подоходном налоге — 610 000 символов) при последовательном запросе статей одного и того же закона (вторая и последующие статьи возвращаются мгновенно). Также исправлена ошибка параметра размера страницы в запросе истории (numOfRows→display), что сократило количество HTTP-запросов с 5 до 1 (измерено: холодный запрос 1 статьи — 1,1 с → 0,6 с).

v3 — Добавление Системы местного налогового законодательства (olta.re.kr)

Системы нумерации дел Налоговой палаты для государственных и местных налогов различаются.

• Государственные налоги: 조심-ГГГГ-Код_регионального_управления-NNNN (например, 조심-2023-서-9465)

• Местные налоги: 조심ГГГГ지NNNN (например, 조심2026지0284)

Фактически, при поиске по одному и тому же ключевому слову в обеих системах, решения Налоговой палаты почти не пересекаются (система Налоговой службы не индексирует дела по местным налогам). Тем не менее, для надежности инструмент nts_and_olta_precedent_search нормализует номера документов, удаляет дубликаты и сообщает количество удаленных дубликатов (duplicates_removed).

Состав файлов

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 처리, 서버컴퓨터에서 직접 생성

Предоставляемые инструменты

server.py предоставляет 6 базовых инструментов, server_ext.py — 6 базовых + 8 от Министерства законодательства = всего 14 инструментов. Фактический рабочий сервер (серверный компьютер) работает на server_ext.py, и все 14 инструментов доступны.

6 базовых (государственные и местные налоги, server.py)

8 расширенных (Министерство законодательства law.go.kr, добавляются только в server_ext.py)

v4 — Функция углубленного поиска (полное отражение кандидатов на улучшение)

• Пагинация, период, сортировка OLTA: Глубокий поиск по определенной категории с шагом 10 результатов с помощью olta_collection_search. Период (ГГГГММДД) и сортировка по новизне обрабатываются на стороне сервера для точности.

• Запрос текста OLTA: Получение полного текста решений Налоговой палаты и Конституционного суда (резюме решения, краткое описание меры, суждение) с помощью olta_get_detail.

• Фильтр по налогу на стороне сервера NTS: Если в tax_type_filter передать точное название налога (налог на прирост капитала, налог на прибыль организаций, налог на добавленную стоимость, налог на наследство и дарение, налог на совокупную недвижимость и т.д. — 14 видов), автоматически применяется фильтр кода на стороне сервера, обеспечивая точную фильтрацию на основе всех данных.

Подробные спецификации данных и таблицы кодов см. в DATA_SOURCES.md.

Исправление ошибок v2.1 (Важно)

Исправлены проблемы, обнаруженные в ходе работы с папкой client/.

• Проблема, когда фильтр даты (date_from/date_to) полностью ломал поиск — на экране интегрированного поиска taxlaw.nts.go.kr изначально нет интерфейса фильтра по периоду, поэтому серверные параметры bltnStrtDtm/bltnEndDtm, добавленные по предположению в предыдущей версии, обрабатывались как неверные значения, что приводило к нулевому количеству результатов поиска. В этот раз эти параметры были удалены и заменены на фильтр на стороне клиента, который отфильтровывает результаты по полю date после их получения.

• Также исправлена проблема, когда в поле номера документа (doc_no) не удалялись маркеры подсветки поискового запроса (<!HS>, <!HE>), из-за чего точное совпадение в nts_ruling_get_by_doc_no не срабатывало.

Независимый клиент для обхода MCP-коннектора (client/)

В папку client/ добавлен независимый клиент, который может напрямую подключаться к серверу и выполнять поиск, минуя MCP, когда соединение с коннектором Claude нестабильно. Инструкции по использованию см. в client/README.md.

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

Улучшения v2

После первой версии были улучшены следующие пункты.

1. Проверка локального запуска

pip install -r requirements.txt
python server.py

По умолчанию сервис работает по адресу http://0.0.0.0:8000/mcp в режиме streamable-http. Порт можно изменить с помощью переменной окружения PORT.

PORT=8765 python server.py

Опции переменных окружения

2. Развертывание

2-A. Текущий метод работы — постоянная работа на серверном компьютере + Tailscale Funnel (с 2026-08)

После остановки сервера из-за исчерпания кредитов Railway (2026-08-08) был осуществлен переход на постоянную работу на собственном серверном компьютере. 14 инструментов (server_ext.py) работают по этому методу.

1. Однократный запуск setup.ps1 в PowerShell от имени администратора на серверном компьютере — загружает исходный код с GitHub, устанавливает зависимости, регистрирует задачу nts-tax-mcp в Планировщике задач Windows (автоматический запуск с правами SYSTEM при загрузке) и немедленно запускает ее.

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

2. run_server.bat устанавливает PORT=8734 и запускает server_ext.py (лог: server.log). LAW_API_OC не записывается непосредственно в этот файл, а загружается из локального файла, находящегося в .gitignore (local_env.bat — одна строка set LAW_API_OC=ваш_код_организации). Если этого файла нет, 8 инструментов Министерства законодательства не будут работать, но 6 базовых будут работать нормально.

3. Установите Tailscale, войдите в систему и откройте внешний доступ по фиксированному адресу через Funnel.

   tailscale funnel --bg 8734

4. Фактический URL MCP-сервера (фиксированный): https://desktop-ika1349.tail81ecba.ts.net/mcp

При изменении порта необходимо одновременно изменить PORT в run_server.bat и целевой порт в tailscale funnel. Не перенаправляйте этот порт напрямую на маршрутизаторе, используйте только Tailscale Funnel.

2-B. Развертывание на Railway (устаревшее)

Поскольку Procfile по-прежнему запускает python server.py, при развертывании на Railway будут доступны только 6 базовых инструментов, а 8 инструментов Министерства законодательства (server_ext.py) не будут включены. При исчерпании кредитов сервер просто останавливается, поэтому в настоящее время этот метод не рекомендуется, но он все еще работает.

1. Загрузите эту папку в репозиторий GitHub.

2. В Railway выберите "New Project" → "Deploy from GitHub repo".

3. Railway распознает Procfile и автоматически запустит python server.py. (Переменная окружения PORT будет автоматически внедрена Railway.)

4. После завершения развертывания адрес, состоящий из домена, выданного Railway, с добавлением /mcp, станет фактическим URL MCP-сервера.

3. Регистрация в Claude в качестве коннектора

1. Зайдите на claude.ai → Профиль → Настройки (Settings) → Коннекторы (Connectors)

2. Нажмите "Добавить пользовательский коннектор (Add custom connector)"

3. Имя: любое желаемое имя (текущее имя рабочего коннектора: Korea nts)

4. URL: введите адрес .../mcp, полученный на шаге 2, и сохраните (текущий рабочий адрес: https://desktop-ika1349.tail81ecba.ts.net/mcp)

5. Установите разрешения инструментов на "Всегда разрешать" (значение по умолчанию "Требуется одобрение" будет запрашивать одобрение каждый раз)

6. Откройте совершенно новый диалог и проверьте, отображаются ли инструменты в списке (сразу после включения нового коннектора он может не отобразиться в уже открытых диалогах)

4. Примеры использования (в чате Claude)

• "Найди в Центре налогового законодательства разъяснения по запросам и прецеденты апелляций, связанные с зонами регулирования"

• "Проверь, есть ли недавние решения Налоговой палаты по непризнанию сделок с нерыночными условиями. Только после 2024 года."

• "Покажи полный текст прецедента 조심-2023-서-9465" (прямой запрос по номеру дела)

• "Отфильтруй только по налогу на прирост капитала и покажи снова" (фильтр по налогу)

• "Найди прецеденты апелляций по местным налогам, связанные с повышенным налогом на приобретение" (местные налоги → olta_ruling_search)

• "Проверь, есть ли решения Счетной палаты, связанные с датой налогообложения налога на имущество" (местные налоги → olta_ruling_search)

• "Найди все прецеденты апелляций по государственным и местным налогам, связанные с зонами регулирования, без дубликатов" (→ nts_and_olta_precedent_search)

• "Найди примеры толкования законов по ликвидационным суммам" (→ law_interpretation_search)

• "Покажи историю Указа о применении Закона о подоходном налоге" (→ law_history_search)

• "Покажи статью 17 Закона о налоге на добавленную стоимость, действовавшую на 15 июля 2008 года" (→ law_article_as_of)

• "Найди основные общие правила Закона о налоге на прибыль организаций" (→ admin_rule_search)

• "Проверь дату вступления в силу налогового соглашения между Кореей и Гонконгом" (→ treaty_search)

• "Найди постановление о льготах по налогу на приобретение в Сеуле" (→ ordinance_search)

5. Независимая проверка состояния сервера (без Claude)

Это скрипт для быстрого определения, является ли проблема проблемой самого сервера или проблемой со стороны Claude, когда инструменты не обнаруживаются в чате Claude. Он отправляет запросы непосредственно на сервер по протоколу MCP, минуя Claude, и проверяет весь поток: initialize → tools/list → tools/call.

python test_mcp_client.py

Значение URL в скрипте по умолчанию оставлено как адрес старого сервера Railway (https://web-production-10fe2.up.railway.app/mcp), но Railway больше не работает из-за исчерпания кредитов (см. 2-A). Для проверки текущего работающего сервера обязательно укажите фактический адрес с помощью --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

Если все эти скрипты выполняются успешно, но инструменты не отображаются в чате Claude, причина не в сервере, а в проблеме распознавания/кэширования коннектора со стороны Claude. В этом случае попробуйте следующее.

• Проверьте в совершенно новом окне чата (сразу после включения коннектора он может не отображаться в старом окне)

• Настройки → Коннекторы, удалите этот коннектор и зарегистрируйте заново

• Если всё ещё не работает, обратитесь в support.claude.com (возможна задержка отражения или баг на стороне платформы Claude)

Справочник параметров инструментов

nts_ruling_search

nts_ruling_get_by_doc_no

olta_ruling_search (местные налоги)

nts_and_olta_precedent_search (объединённый поиск по национальным и местным налогам, с удалением дубликатов)

Возвращаемое значение включает nts_precedent, olta_precedent, duplicates_removed (фактическое количество удалённых дубликатов).

olta_collection_search (углублённый поиск по местным налогам)

olta_get_detail (просмотр текста местных налогов)

Возвращает полный текст решения, включая ключевые моменты, ссылки на законы, краткое изложение дела, соображения и т.д.

court_case_search (судебные прецеденты, server_ext.py)

court_case_detail (server_ext.py)

law_interpretation_search (толкование законов, server_ext.py)

law_history_search (история закона, server_ext.py)

law_article_as_of (статья на определённую дату, server_ext.py)

admin_rule_search (административные правила, server_ext.py)

treaty_search (налоговые соглашения, server_ext.py)

ordinance_search (местные постановления, server_ext.py)

Известные ограничения (по состоянию на v5)

• 8 инструментов law.go.kr доступны только при запуске через server_ext.py. При отдельном запуске server.py отображаются только базовые 6.

• Белый список IP-адресов law.go.kr: при вызове с незарегистрированного IP-адреса все 8 инструментов возвращают ошибку "Ошибка аутентификации". Необходимо сначала зарегистрировать публичный IP-адрес сервера в open.law.go.kr → История заявок OpenAPI.

• Парсинг XML law.go.kr: ответ обрабатывается лёгким парсером на основе регулярных выражений. При изменении структуры ответа API (например, изменение имени тега) парсинг может нарушиться.

• law_article_as_of: автоматически выбирает версию с максимальной датой вступления в силу, не превышающей указанную дату, среди исторических версий. Если существует несколько законов с одинаковым названием (основной закон, указ о применении, правила), без указания law_id может быть выбрана непреднамеренная версия.

• Фильтр по виду налога NTS: при точном названии налога (14 видов, включая налог на доходы от прироста капитала, см. таблицу кодов в DATA_SOURCES.md) применяется фильтр на стороне сервера, при других строках — постобработка на стороне клиента.

• Фильтр по дате NTS: подтверждено (измерениями), что в API общего поиска нет параметра даты, поэтому date_from/date_to обрабатываются фильтром на стороне клиента. Более стабильно использовать вместе с сортировкой по новизне (sort=date_desc).

• Запросы на пересмотр в Счётную палату (национальные налоги): не входят в область действия этого сервера. (Решения Счётной палаты по местным налогам покрываются olta_ruling_search / olta_collection_search).

• nts_ruling_get_by_doc_no: отдельный API детального просмотра не подтверждён, поэтому реализован путём использования номера документа в качестве поискового запроса.

• Парсинг HTML OLTA: olta.re.kr отвечает в формате HTML, поэтому парсится с помощью BeautifulSoup. При изменении структуры страницы сайта (имена классов p.se_title, ul.search_out и т.д.) парсинг может нарушиться.

• olta_ruling_search (общий поиск) возвращает только 3 предварительных просмотра на категорию. Если нужно больше результатов, используйте olta_collection_search (10 записей на страницу, поддерживает пагинацию, фильтр по дате, сортировку).

• Просмотр текста olta_get_detail поддерживается только для Налогового трибунала и Конституционного суда. Судебная практика не поддерживается из-за структуры URL, требующей двух параметров; для официальных толкований используется краткое содержание (summary).

• Ответы на запросы местных органов власти: кодовая таблица внутри olta.re.kr существует, но на экране результатов общего поиска не отображается, поэтому в настоящее время поиск невозможен.

• Удаление дубликатов: система нумерации дел Налогового трибунала по национальным и местным налогам различается, поэтому фактическое дублирование не происходит, что подтверждено измерениями; удаление дубликатов на основе нормализации в nts_and_olta_precedent_search является мерой предосторожности.