opinet-mcp

韓国石油公社 Opinet の燃料価格情報無料APIを、Claude / Claude CodeなどのMCPクライアントで使用できるようにするMCPサーバーです。

• 言語: TypeScript (ESM)

• SDK: @modelcontextprotocol/sdk

• トランスポート: stdio

• 呼び出し制限: 1,500回/日 (Opinetのポリシー)

事前準備

1. Opinet無料API でAPIキーを発行

2. Node.js 18以上 (グローバル fetch を使用)

インストール & 実行 — 3つの方法

方法 1. npxで即時実行 (推奨 · 別途インストール不要)

npmレジストリにpublish後に使用可能。publishは以下の「配布」セクションを参照。

OPINET_API_KEY=발급키 npx -y opinet-mcp

方法 2. グローバルインストール

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

方法 3. ソースクローン (開発 / private使用)

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方式 (最も簡単 — publish後に使用)

{
  "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キーなしで実行 → 環境変数の案内後に終了すればビルド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)

初回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

publish後は誰でも npx -y opinet-mcp で即時使用可能です。

prepare スクリプトがあるため、 npm install 時に自動ビルドされます。つまり、GitHubから直接インストール (npm i github:KimJintak/opinet-mcp) しても動作します。

ライセンス

MIT.

データソースは韓国石油公社Opinetであり、データ使用時は Opinet利用規約 に従ってください。