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.

Related MCP server: OpenDART MCP Server

Включенные 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 Национальной правовой информации, API информации Национального собрания

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

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

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

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

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

Лицензия

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