nts-taxlaw-mcp

MCP-сервер для прямого запроса к оригиналу Системы информации о налоговом законодательстве Национальной налоговой службы (https://taxlaw.nts.go.kr).

Реализовано на Python и FastMCP, использует собственные конечные точки запроса ННС, минуя зеркало Министерства законодательства (ntsCgmExpc).

• Поиск последних разъяснений налогового законодательства

• Структурирование подробного текста: ответы, суждения, выводы и т.д.

• Точный поиск по номеру документа

• Поиск судебных прецедентов, решений и административных стандартов толкования

• Структурированный ответ с указанием источника и типа основания

Существующий korean-law-mcp из-за особенностей OPEN API Министерства законодательства позволяет искать список разъяснений ННС, но имеет ограничения при запросе подробного текста. nts-taxlaw-mcp напрямую запрашивает оригинал ННС и предоставляет поиск по номеру документа и запрос подробного текста.

1. Поддерживаемые данные

Объём данных

По состоянию на август 2026 года.

Неподдерживаемые данные

Дополнительные сведения об исследовании см. в docs/INVESTIGATION.md.

Related MCP server: korean-engineering-mcp

2. Источники данных

Все данные запрашиваются из Системы информации о налоговом законодательстве Национальной налоговой службы.

https://taxlaw.nts.go.kr

• Используется открытая конечная точка POST /action.do

• Без обхода логина, CAPTCHA и контроля доступа

• Не требуются отдельные сессии, куки или ключи аутентификации

• Все ответы содержат информацию для отслеживания оригинала

{
  "sourceAgency": "국세청",
  "sourceSystem": "국세법령정보시스템",
  "sourceId": "200000000000022584",
  "documentNumber": "서면-2026-법규재산-0119",
  "sourceUrl": "https://taxlaw.nts.go.kr/qt/USEQTA002P.do?ntstDcmId=200000000000022584",
  "retrievedAt": "2026-08-19T13:34:58Z"
}

3. Поиск по номеру документа

Нормализует различия в написании номеров документов для поиска одного и того же документа.

서면-2026-법규재산-0119
서면 2026 법규재산 0119
서면2026법규재산0119
서면서면-2026-법규재산-0119
질의회신 서면-2026-법규재산-0119
질의회신서면-2026-법규재산-0119
국세청 서면-2026-법규재산-0119

Подтверждённые форматы номеров документов:

A и B различаются по тому, является ли второй элемент четырёхзначным годом.

Принцип точного совпадения

정확히 일치
→ found: true
→ exactMatch: true
→ document 반환

일치 없음
→ NOT_FOUND
→ similarDocuments 별도 반환

Документы с частичным совпадением не возвращаются как правильный ответ.

lookup_tax_document("법규재산-0119")

→ [NOT_FOUND]

similarDocuments:
  · 서면-2026-법규재산-0119
  · 서면-2015-징세-0119
  · 기준-2023-법규부가-0044
  · 적부-국세청-2020-0119

similarDocuments — это вспомогательная информация для поиска, не считается запрошенным документом.

Если различается только нулевое заполнение, например 0119 и 119, они обрабатываются как один и тот же номер документа. Нормализация используется только для расширения кандидатов на поиск; в окончательном ответе возвращается номер документа из оригинала ННС без изменений.

4. Поиск по ключевым словам

Применяется синтаксис поиска на основе фактических результатов поиска в Системе информации о налоговом законодательстве.

В MCP используется следующим образом:

{"query": "상속 공동상속주택"}                  # AND
{"query": "상속 증여", "match": "any"}         # OR
{"query": "상속", "exclude": ["증여"]}         # NOT
{"query": '"공동상속주택 소수지분" 양도'}       # 구절 검색

При поиске обратите внимание на следующее:

• Для оператора OR используется ASCII-символ вертикальной черты |.

• ¦ (U+00A6) не работает как OR.

• При передаче неверного поля сортировки возвращается не ошибка, а 0 результатов.

• На сервере используются только проверенные на практике DCM_RGT_DTM, FRS_RGT_DTM, SCORE.

5. Установка

Нет необходимости устанавливать Python вручную или создавать виртуальное окружение. uv управляет необходимым Python и пакетами.

5.1 Установка uv

Windows

PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Если выполнение скриптов ограничено корпоративной политикой:

winget install --id=astral-sh.uv -e

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

После установки перезапустите терминал и проверьте.

uv --version

5.2 Установка сервера

Можно установить напрямую с адреса GitHub.

uv tool install git+<GitHub 주소>

После установки команда nts-taxlaw-mcp будет доступна из любого пути.

Проверка места установки:

(Get-Command nts-taxlaw-mcp).Source

which nts-taxlaw-mcp

Обычные пути установки:

Обновление:

uv tool upgrade nts-taxlaw-mcp

Удаление:

uv tool uninstall nts-taxlaw-mcp

5.3 Установка из исходников

Если вы хотите изменить код или запустить тесты, скачайте репозиторий.

git clone <GitHub 주소>
cd nts-taxlaw-mcp
uv sync

uv sync выполняет следующие действия:

• Проверяет и устанавливает Python, соответствующий requires-python = ">=3.11"

• Создаёт .venv в каталоге проекта

• Устанавливает зависимости на основе uv.lock

Нет необходимости активировать виртуальное окружение вручную. Дальнейшие команды выполняются через uv run.

В средах без git можно скачать Code > Download ZIP с GitHub, распаковать и выполнить uv sync.

Проверка работы:

uv run nts-taxlaw-mcp --help
uv run python scripts/compare_with_site.py

5.4 Проверка PATH

Если сразу после установки команда uv или nts-taxlaw-mcp не найдена, перезапустите терминал и проверьте.

uv tool update-shell

Проверка в Windows с абсолютным путём:

& "$env:USERPROFILE\.local\bin\uv.exe" --version

macOS / Linux:

~/.local/bin/uv --version

6. Подключение к Claude Code

При установке через uv tool

claude mcp add nts-taxlaw -- nts-taxlaw-mcp

Если команда не найдена, проверьте путь установки и укажите абсолютный путь.

claude mcp add nts-taxlaw -- "C:\Users\<사용자>\.local\bin\nts-taxlaw-mcp.exe"

При запуске из репозитория

claude mcp add nts-taxlaw -- uv run --directory /절대경로/nts-taxlaw-mcp nts-taxlaw-mcp

Проверка регистрации:

claude mcp list

HTTP-подключение

Запуск сервера:

nts-taxlaw-mcp --http --port 8000

Регистрация в Claude Code:

claude mcp add --transport http nts-taxlaw http://127.0.0.1:8000/mcp

7. Подключение к Claude Desktop

Файл конфигурации:

В Claude Desktop надёжнее указывать абсолютный путь к исполняемому файлу.

Windows

Установка через uv tool:

{
  "mcpServers": {
    "nts-taxlaw": {
      "command": "C:\\Users\\<사용자>\\.local\\bin\\nts-taxlaw-mcp.exe"
    }
  }
}

Запуск из репозитория:

{
  "mcpServers": {
    "nts-taxlaw": {
      "command": "C:\\Users\\<사용자>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\<사용자>\\nts-taxlaw-mcp",
        "nts-taxlaw-mcp"
      ]
    }
  }
}

В JSON обратные слэши в путях Windows записываются как \\. Можно также использовать /.

macOS

Установка через uv tool:

{
  "mcpServers": {
    "nts-taxlaw": {
      "command": "/Users/<사용자>/.local/bin/nts-taxlaw-mcp"
    }
  }
}

Запуск из репозитория:

{
  "mcpServers": {
    "nts-taxlaw": {
      "command": "/Users/<사용자>/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/<사용자>/nts-taxlaw-mcp",
        "nts-taxlaw-mcp"
      ]
    }
  }
}

Фактический путь можно проверить следующей командой:

(Get-Command nts-taxlaw-mcp).Source

which nts-taxlaw-mcp

Использование вместе с korean-law-mcp

Рекомендуется запрашивать текст законов, указов и правил из korean-law-mcp, а уникальные материалы ННС — из nts-taxlaw-mcp.

{
  "mcpServers": {
    "korean-law": {
      "command": "npx",
      "args": ["-y", "korean-law-mcp"],
      "env": {
        "LAW_OC": "발급받은-인증키"
      }
    },
    "nts-taxlaw": {
      "command": "C:\\Users\\<사용자>\\.local\\bin\\nts-taxlaw-mcp.exe"
    }
  }
}

pip + venv

В средах, где нельзя использовать uv, можно установить Python 3.11 или выше вручную и запустить традиционным способом.

git clone <GitHub 주소>
cd nts-taxlaw-mcp

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

python -m nts_taxlaw_mcp --help

Активация виртуального окружения в Windows:

.venv\Scripts\activate

В Claude Desktop укажите абсолютный путь к Python в виртуальном окружении.

{
  "mcpServers": {
    "nts-taxlaw": {
      "command": "/절대경로/nts-taxlaw-mcp/.venv/bin/python",
      "args": ["-m", "nts_taxlaw_mcp"]
    }
  }
}

8. Переменные окружения

Все параметры необязательны, сервер работает с значениями по умолчанию.

9. Инструменты MCP

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

Если номер документа известен, сначала используйте lookup_tax_document.

get_tax_document объединяет детальный запрос разъяснений и решений в один инструмент. Поскольку действие детального запроса в Системе информации о налоговом законодательстве одинаково независимо от типа документа, отдельный инструмент для детального запроса не выделяется.

Примеры использования

Поиск по номеру документа:

{
  "name": "lookup_tax_document",
  "arguments": {
    "document_number": "서면-2026-법규재산-0119"
  }
}

Пример ответа:

[OK]

found: true
exactMatch: true

서면-2026-법규재산-0119
질의회신 | 양도소득세 | 2026-08-11 | nts_ruling

title:
인구감소지역 내 취득한 분양권이 ’27.1.1.이후 주택으로 전환된 경우 조특법§71의2 적용 여부

relatedLaws:
- 조세특례제한법 제71조의2
- 조세특례제한법 시행령 제68조의2

sections:
- facts
- question
- relatedLawsText

Поиск судебных прецедентов и решений:

{
  "name": "search_tax_decisions",
  "arguments": {
    "query": "공동상속주택",
    "type": "court",
    "result": ["국승"],
    "limit": 3
  }
}

Поиск общих правил:

{
  "name": "search_tax_guidance",
  "arguments": {
    "kind": "basic_ruling",
    "law_name": "상속세 및 증여세법",
    "query": "상속재산"
  }
}

Сбор обоснований для налогового запроса:

{
  "name": "tax_research",
  "arguments": {
    "question": "부모가 자녀에게 시가보다 낮은 가격으로 아파트를 양도하면 증여세가 발생하는지"
  }
}

10. Классификация юридических оснований

Налоговые материалы возвращаются с разделением по характеру основания.

Прецеденты ННС являются толкованием законодательства налоговым органом и не обязательны для судов. Общие правила и стандарты исполнения — это внутренние стандарты исполнения, а не сами нормативные акты.

11. Обработка ошибок

Различаются случаи, когда материал действительно не существует, и случаи, когда не удалось получить данные из-за проблем с исходным сервером.

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

Даже при ответе HTTP 200, если возвращается HTML-страница технического обслуживания или текст аномально пуст, это обрабатывается как временный сбой и выполняется повторная попытка.

12. Ограничение запросов и кэш

Чтобы не создавать чрезмерную нагрузку на Систему информации о налоговом законодательстве, ограничивается количество вызовов и сокращаются повторные запросы.

Ограничение запросов

• Базовый лимит запросов: 60 в минуту

• Допустимый всплеск: максимум 20

• Используется метод токен-бакета с учётом последовательных запросов в одной задаче, например tax_research

Кэш

Обработка дублирующихся запросов

Если одинаковые запросы поступают одновременно, фактический запрос к Системе информации о налоговом законодательстве выполняется только один раз, а результат используется совместно.

Повторное использование HTTP-соединений

Используется пул keep-alive соединений httpx.

13. Отказ от ответственности

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

• Разъяснения и решения основаны на фактических обстоятельствах конкретного дела.

• Прецеденты ННС являются толкованием законодательства налоговым органом и не обязательны для судов.

• Общие правила и стандарты исполнения — это внутренние стандарты исполнения, а не нормативные акты.

• Для изменённых законов необходимо отдельно проверять дату вступления в силу.

• Точность и актуальность данных зависят от состояния обновления Системы информации о налоговом законодательстве.

• Для решений, требующих юридической силы, необходимо проверять оригинал в Системе информации о налоговом законодательстве.

• Действия, имеющие юридическую силу, такие как фактическая подача деклараций или обжалование, требуют проверки квалифицированными специалистами, например налоговыми консультантами или юристами.

Лицензия

MIT

Сведения об источнике данных см. в NOTICE.