opinet-mcp

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

语言: TypeScript (ESM)
SDK: @modelcontextprotocol/sdk
传输: stdio
调用限制: 1,500 次/天 (Opinet 政策)

前期准备

在 Opinet 免费 API 申请 API Key
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

配置文件位置:

操作系统	路径
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 使用条款。

opinet-mcp

opinet-mcp

前期准备

安装与运行 — 3 种方法

方法 1. 使用 npx 直接运行 (推荐 · 无需额外安装)

方法 2. 全局安装

方法 3. 克隆源码 (开发 / 私有使用)

MCP 客户端注册

Claude Desktop / Claude Code

A. npx 方式 (最简便 — 发布后使用)

B. 全局安装方式

C. 本地构建方式 (克隆源码的情况)

其他 MCP 客户端 (Cursor, Cline, Continue 等)

提供工具 (6 种)

公共代码

坐标系注意事项

使用示例 (自然语言)

运行确认 (冒烟测试)

开发

发布 (npm publish)

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API