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: realestate-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

配置文件位置:

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

公共代码

产品代码 (prodcd)

市道代码 (sido / area 2 位)

市郡区单位为 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 使用条款。