korea-public-data-mcp

Сервер MCP, который позволяет Claude напрямую обращаться к публичным данным Республики Корея (OpenDART Финансовой надзорной службы, ECOS Банка Кореи, KOSIS Статистического управления Кореи, Портал открытых данных) и отвечать на вопросы о финансовых, экономических и статистических показателях на основе реальных ответов API, а не догадок.

Аналогично MCP, использующим данные электронной отчетности DART для ответов на вопросы о финансовой отчетности, этот сервер позволяет Claude вызывать его инструменты для получения актуальных данных в ответ на такие вопросы, как «Сколько составила выручка этой компании в прошлом году?», «Расскажи о последних изменениях ключевой ставки», «Какой сейчас уровень безработицы в нашей стране?».

Название временно установлено как korea-public-data-mcp. При загрузке на GitHub вы можете свободно изменить его на любое другое — на работу кода это не повлияет.

Почему сделано так (принципы проектирования)

Сервер спроектирован с соблюдением трёх ограничений, запрошенных ответственным лицом.

1. Без затрат на LLM/внешние сервисы — этот сервер только «получает» данные. Он не вызывает никаких LLM внутри и не использует платные API. Фактические рассуждения и обобщение выполняет Claude, вызывающий этот MCP, поэтому стоимость эксплуатации сервера практически равна нулю (за исключением электроэнергии/серверных ресурсов).

2. Предотвращение блокировки API (IP-бан) — государственные публичные API могут временно блокироваться при превышении лимитов вызовов в секунду/день. Поэтому:

   • Перед всеми вызовами API установлено ограничение количества вызовов в секунду (token bucket), чтобы самостоятельно замедлять скорость.

   • Повторяющиеся запросы повторно используют кэш в памяти, а для больших статических файлов, таких как список компаний DART, применяется дисковый кэш (по умолчанию 7 дней), предотвращающий повторную загрузку.

   • Данные получаются не отдельными вызовами по каждой статье учёта/периоду, а целыми таблицами и диапазонами периодов за один раз (например, финансовая отчётность получается одним вызовом для всех статей учёта компании, статистика запрашивается сразу за весь период от начала до конца).

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

   • При ответах 429/5xx выполняется до 3 повторных попыток с экспоненциальной задержкой.

3. Запуск каждым через Docker — без развёртывания отдельного сервера, каждый член команды локально запускает docker build + docker run и подключает к своему Claude.

Включённые API (первичный ключевой набор)

Реализация всего списка запросов (около 40) одновременно сделала бы обслуживание сложным, поэтому сначала с высокой степенью готовности реализованы ключевые 4 организации, к которым ответственное лицо обращается чаще всего. Остальные можно добавлять по тому же шаблону, следуя руководству по расширению.

Инструкция по получению ключей API

Даже если у вас ещё нет полученных ключей, сервер запустится нормально, и список инструментов будет отображаться. Однако при фактическом вызове инструментов будет возвращено сообщение об отсутствии ключа, поэтому подавайте заявки по порядку, начиная с необходимых.

Получив ключи, скопируйте .env.example в .env и заполните их.

cp .env.example .env
# .env 파일을 열어 발급받은 키 입력

Быстрый старт (Docker)

git clone <이 레포 주소>
cd korea-public-data-mcp
cp .env.example .env   # 키 채워넣기 (없어도 일단 진행 가능)
docker build -t korea-public-data-mcp .

Зарегистрируйте в настройках MCP Claude Desktop / Claude Code (claude_desktop_config.json и т.д.) следующим образом.

{
  "mcpServers": {
    "korea-public-data": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/절대경로/korea-public-data-mcp/.env",
        "korea-public-data-mcp"
      ]
    }
  }
}

После перезапуска Claude в списке инструментов появятся dart_*, ecos_*, kosis_*, data_go_kr_*. Теперь на вопросы вроде «Расскажи о выручке Samsung Electronics за 2023 год» Claude будет вызывать эти инструменты и отвечать на основе реальных данных.

Локальная разработка/тестирование (без Docker)

python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest
pytest -q                      # 키 없이도 통과하는 스모크 테스트
python -m korea_public_data_mcp.server   # stdio로 직접 실행해보기 (Ctrl+C로 종료)

Руководство по расширению (добавление нового API)

Для добавления всех остальных сервисов из предоставленного ответственным лицом списка (RISS, KIPRIS, Национальная правовая информация, Нараджантер, Сеульская площадь открытых данных и т.д.) достаточно повторить следующий шаблон. Например, для добавления новой организации foo:

1. Добавить элемент foo в API_KEYS в src/korea_public_data_mcp/config.py (env var, URL для получения)

2. Создать src/korea_public_data_mcp/clients/foo.py — используя core/http_client.get_json, написать только логику вызова реальной конечной точки (повторные попытки/ограничение скорости обрабатываются общим клиентом автоматически)

3. Создать src/korea_public_data_mcp/tools/foo_tools.py — обернуть функцию клиента декоратором @mcp.tool(), перехватывать MissingApiKeyError и возвращать информационное сообщение, кэшировать с помощью cached_call

4. Добавить одну строку foo_tools.register(mcp) в src/korea_public_data_mcp/server.py

5. Добавить элементы в .env.example и таблицу README

Благодаря этой структуре при добавлении нового API не нужно каждый раз заново писать логику предотвращения блокировки (ограничение скорости/кэш/пакетная обработка).

Следующие кандидаты на расширение (на основе списка запросов ответственного лица)

• Право/администрирование: Open API национальной правовой информации, Open API информации о Национальном собрании

• Закупки/бизнес: Нараджантер (g2b), Хаб данных о закупках, NTIS Национальная научно-техническая информация

• Академические: RISS, KISTI, OpenAPI Национальной библиотеки Кореи

• Интеллектуальная собственность: KIPRIS Plus (патенты, товарные знаки)

• Региональные: Сеульская площадь открытых данных, Кёнги Дейта Дрим

Сообщите приоритеты или следующий API для подключения, и я продолжу реализацию с этого пункта.

Лицензия

Свободно используйте/изменяйте для внутренних целей.