opinet-mcp

Dies ist ein MCP-Server, der es ermöglicht, die kostenlose Kraftstoffpreis-API Opinet der Korea Petroleum Corporation in MCP-Clients wie Claude / Claude Code zu nutzen.

• Sprache: TypeScript (ESM)

• SDK: @modelcontextprotocol/sdk

• Transport: stdio

• Aufruflimit: 1.500 Aufrufe/Tag (gemäß Opinet-Richtlinie)

Voraussetzungen

1. API-Schlüssel bei Opinet Free API beantragen

2. Node.js 18 oder höher (verwendet globales fetch)

Installation & Ausführung — 3 Methoden

Methode 1. Sofortige Ausführung mit npx (empfohlen · keine separate Installation erforderlich)

Nach der Veröffentlichung im npm-Register verfügbar. Informationen zur Veröffentlichung finden Sie im Abschnitt "Veröffentlichung" unten.

OPINET_API_KEY=발급키 npx -y opinet-mcp

Methode 2. Globale Installation

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

Methode 3. Quellcode klonen (für Entwicklung / private Nutzung)

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-Client-Registrierung

Claude Desktop / Claude Code

Speicherort der Konfigurationsdatei:

A. npx-Methode (am einfachsten — nach Veröffentlichung verwenden)

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

B. Globale Installationsmethode

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

C. Lokale Build-Methode (falls Quellcode geklont wurde)

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

⚠️ Claude Desktop erbt den PATH nur eingeschränkt. Wenn command: "node" oder "npx" nicht gefunden werden, geben Sie den absoluten Pfad an (z. B. /opt/homebrew/bin/node, /usr/local/bin/npx). Überprüfen Sie dies im Terminal mit which node / which npx.

Nach der Konfiguration Claude Desktop vollständig beenden (Cmd+Q) → neu starten, dann sollten die 6 Tools im Tool-Symbol sichtbar sein.

Andere MCP-Clients (Cursor, Cline, Continue, etc.)

Sie können die Konfiguration analog zur JSON-Struktur in die MCP-Server-Konfigurationsdatei des jeweiligen Clients einfügen.

Verfügbare Tools (6 Typen)

Gemeinsame Codes

Produktcode (prodcd)

Provinzcode (sido / area 2-stellig)

Die Ebene der Stadt/Landkreis/Bezirk verwendet einen 4-stelligen Code (z. B. 0207 = Gyeonggi Gwangmyeong-si). Kann separat über den Opinet-Endpunkt areaCode.do abgefragt werden.

Hinweise zu Koordinatensystemen

Die Eingabekoordinaten (x, y) für search_stations_around sowie alle GIS_X_COOR / GIS_Y_COOR in den Antworten basieren auf dem KATEC-Koordinatensystem. Dies unterscheidet sich von WGS84 (Breitengrad/Längengrad). Wenn Sie Breitengrad/Längengrad als Eingabe verwenden möchten, konvertieren Sie diese bitte clientseitig in KATEC, bevor Sie den Aufruf tätigen.

Anwendungsbeispiele (natürliche Sprache)

• "Wie hoch ist der landesweite Benzin-Durchschnittspreis heute?" → get_national_average_price

• "Durchschnittspreis für Diesel in Seoul" → get_sido_average_price (sido=01, prodcd=D047)

• "Benzin-Trend der letzten 7 Tage" → get_recent_7days_price (prodcd=B027)

• "Die 5 günstigsten Tankstellen für Benzin in Gwangmyeong-si" → get_lowest_price_top20 (prodcd=B027, area=0207, cnt=5)

• "Details zur Tankstelle mit ID A0008322" → get_station_detail

Funktionsprüfung (Smoke Test)

Ausführung ohne API-Schlüssel → Wenn nach dem Hinweis auf Umgebungsvariablen beendet wird, ist der Build OK:

node dist/index.js

Direkter Aufruf über stdio bei vorhandenem API-Schlüssel:

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

Entwicklung

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

Projektstruktur:

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

Veröffentlichung (npm publish)

Bei der ersten Veröffentlichung:

# 1) npm 로그인
npm login

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

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

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

Nachfolgende Versions-Updates:

npm version patch   # 0.1.0 -> 0.1.1
npm publish

Nach der Veröffentlichung kann jeder das Tool sofort mit npx -y opinet-mcp nutzen.

Da ein prepare-Skript vorhanden ist, erfolgt der Build bei npm install automatisch. Das bedeutet, es funktioniert auch bei direkter Installation von GitHub (npm i github:KimJintak/opinet-mcp).

Lizenz

MIT.

Die Datenquelle ist Opinet der Korea Petroleum Corporation. Bitte beachten Sie bei der Datennutzung die Nutzungsbedingungen von Opinet.