Skip to main content
Glama
opinet-mcp

opinet-mcp

by KimJintak

opinet-mcp

这是一个 MCP 服务器,允许在 Claude / Claude Code 等 MCP 客户端中使用韩国石油公社 Opinet 的免费油价信息 API。

  • 语言: TypeScript (ESM)

  • SDK: @modelcontextprotocol/sdk

  • 传输: stdio

  • 调用限制: 1,500 次/天 (Opinet 政策)


前期准备

  1. 在 Opinet 免费 API 申请 API Key

  2. Node.js 18 或以上版本 (使用全局 fetch)


Related MCP server: fuel-map-mcp

安装与运行 — 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

配置文件位置:

操作系统

路径

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

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 等)

按照与上述 JSON 结构相同的方式,添加到各客户端的 MCP 服务器配置文件中即可。


提供工具 (6 种)

工具名称

Opinet 端点

说明

get_national_average_price

avgAllPrice.do

全国加油站平均价格 (当前)

get_sido_average_price

avgSidoPrice.do

各市道加油站平均价格 (当前)

get_recent_7days_price

avgRecentPrice.do

最近 7 天全国日均价格 (趋势)

get_lowest_price_top20

lowTop10.do

全国/地区最低价加油站 TOP20

search_stations_around

aroundAll.do

基于 KATEC 坐标的周边加油站搜索

get_station_detail

detailById.do

通过加油站 ID (UNI_ID) 查询详情

公共代码

产品代码 (prodcd)

代码

产品

B027

普通汽油

D047

汽车柴油

B034

高级汽油

C004

室内煤油

K015

汽车丁烷

市道代码 (sido / area 2 位)

代码

地区

代码

地区

01

首尔

10

釜山

02

京畿

11

济州

03

江原

12

大邱

04

忠北

13

仁川

05

忠南

14

光州

06

全北

15

大田

07

全南

16

蔚山

08

庆北

17

世宗

09

庆南

市郡区单位为 4 位代码 (例如: 0207 = 京畿道光明市)。可通过 Opinet 的 areaCode.do 端点单独查询。

坐标系注意事项

search_stations_around 的输入坐标 (x, y) 以及所有响应中的 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


运行确认 (冒烟测试)

不带 API Key 运行 → 提示环境变量后退出即表示构建成功:

node dist/index.js

有 API Key 时,通过 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 使用条款。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool targets a distinct data view (cheapest stations, national average, historical trends, regional averages, single station details). While all relate to fuel prices, the scope filters (top20, 7-day history, sido codes) create clear boundaries.

    Naming Consistency5/5

    All tools use consistent snake_case with a 'get_' verb prefix followed by descriptive noun phrases (lowest_price_top20, national_average_price, etc.). The pattern is predictable throughout.

    Tool Count4/5

    Five tools cover the essential read-only queries for a fuel price information service without bloat. The scope is well-contained, though an additional search-by-radius or brand filter could round it out.

    Completeness4/5

    Core price discovery workflows are covered: finding cheap stations, checking averages at national/regional levels, viewing trends, and drilling into station details. Minor gaps include no brand-specific queries or historical data beyond 7 days.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    Appeared in Searches