opinet-mcp

Это MCP-сервер, который позволяет использовать бесплатный API информации о ценах на топливо Opinet от Корейской нефтяной корпорации в MCP-клиентах, таких как Claude / Claude Code.

• Язык: TypeScript (ESM)

• SDK: @modelcontextprotocol/sdk

• Транспорт: stdio

• Лимит вызовов: 1500 вызовов/день (политика Opinet)

Предварительные требования

1. Получите API-ключ на сайте Opinet Free API

2. Node.js версии 18 или выше (используется глобальный fetch)

Установка и запуск — 3 способа

Способ 1. Мгновенный запуск через npx (рекомендуется, установка не требуется)

Доступно после публикации в реестре npm. Информацию о публикации см. в разделе "Развертывание" ниже.

OPINET_API_KEY=발급키 npx -y opinet-mcp

Способ 2. Глобальная установка

npm install -g opinet-mcp
OPINET_API_KEY=발급키 opinet-mcp

Способ 3. Клонирование исходного кода (для разработки / частного использования)

git clone https://github.com/KimJintak/opinet-mcp.git
cd opinet-mcp
npm install
npm run build
OPINET_API_KEY=발급키 node dist/index.js

Регистрация в MCP-клиенте

Claude Desktop / Claude Code

Расположение файла конфигурации:

A. Способ через npx (самый простой — после публикации)

{
  "mcpServers": {
    "opinet": {
      "command": "npx",
      "args": ["-y", "opinet-mcp"],
      "env": {
        "OPINET_API_KEY": "발급받은_키"
      }
    }
  }
}

B. Способ через глобальную установку

{
  "mcpServers": {
    "opinet": {
      "command": "opinet-mcp",
      "env": {
        "OPINET_API_KEY": "발급받은_키"
      }
    }
  }
}

C. Способ локальной сборки (если клонировали исходный код)

{
  "mcpServers": {
    "opinet": {
      "command": "node",
      "args": ["/절대/경로/opinet-mcp/dist/index.js"],
      "env": {
        "OPINET_API_KEY": "발급받은_키"
      }
    }
  }
}

⚠️ Claude Desktop имеет ограниченное наследование PATH. Если при запуске через command: "node" или "npx" возникают ошибки, укажите абсолютный путь (например, /opt/homebrew/bin/node, /usr/local/bin/npx и т.д.). Проверьте путь с помощью which node / which npx в терминале.

После настройки полностью закройте Claude Desktop (Cmd+Q) → перезапустите, и вы увидите 6 инструментов в иконке инструментов.

Другие MCP-клиенты (Cursor, Cline, Continue и др.)

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

Доступные инструменты (6 типов)

Общие коды

Код продукта (prodcd)

Код региона (sido / area, 2 цифры)

Уровень городов/районов (сигунгу) использует 4-значный код (например, 0207 = Кёнги, Кванмён). Можно запросить отдельно через эндпоинт Opinet areaCode.do.

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

Входные координаты (x, y) для search_stations_around и все значения GIS_X_COOR / GIS_Y_COOR в ответах используют систему координат KATEC. Она отличается от WGS84 (широта/долгота), поэтому, если вы принимаете широту/долготу на входе, преобразуйте их в KATEC перед вызовом.

Примеры использования (естественный язык)

• "Покажи среднюю цену на бензин по стране сегодня" → get_national_average_price

• "Средняя цена на дизель в Сеуле" → get_sido_average_price (sido=01, prodcd=D047)

• "Тренд цен на бензин за последние 7 дней" → get_recent_7days_price (prodcd=B027)

• "5 самых дешевых АЗС с бензином в Кванмёне" → get_lowest_price_top20 (prodcd=B027, area=0207, cnt=5)

• "Подробная информация об АЗС с ID A0008322" → get_station_detail

Проверка работоспособности (Smoke Test)

Запуск без API-ключа → если выводится инструкция по переменным окружения и завершается, сборка OK:

node dist/index.js

При наличии API-ключа, прямой вызов через stdio:

export OPINET_API_KEY=발급키

# 등록된 툴 목록 확인
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

# 전국 평균가격 호출
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_national_average_price","arguments":{}}}' | node dist/index.js

Разработка

npm install
npm run dev      # tsc --watch
npm run build    # 한 번 빌드
npm start        # dist/index.js 실행
npm run clean    # dist 삭제

Структура проекта:

opinet-mcp/
├── src/
│   └── index.ts          # MCP 서버 본체
├── dist/                 # 빌드 결과물 (배포 대상)
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

Развертывание (npm publish)

При первой публикации:

# 1) npm 로그인
npm login

# 2) package.json의 author / repository / name 확인 (필요하면 scoped: @yourname/opinet-mcp)

# 3) 빌드 + publish (prepublishOnly에서 자동 빌드됨)
npm publish

# scoped 패키지면
npm publish --access public

Последующие обновления версии:

npm version patch   # 0.1.0 -> 0.1.1
npm publish

После публикации любой желающий может сразу использовать команду npx -y opinet-mcp.

Благодаря скрипту prepare сборка происходит автоматически при npm install. Это означает, что установка напрямую из GitHub (npm i github:KimJintak/opinet-mcp) также будет работать.

Лицензия

MIT.

Источник данных — Opinet Корейской нефтяной корпорации. При использовании данных соблюдайте Условия использования Opinet.