Opinet

БесплатноHosted

Provides access to Korea Petroleum Corporation's Opinet fuel price API for South Korea. Enables querying of current national and regional fuel averages, recent

автор: KimJintak

GitHub

Описание

Provides access to Korea Petroleum Corporation's Opinet fuel price API for South Korea. Enables querying of current national and regional fuel averages, recent price trends, lowest-price stations, and nearby gas station details through natural language.

README

한국석유공사 오피넷(Opinet) 유가정보 무료 API를 Claude / Claude Code 등 MCP 클라이언트에서 사용할 수 있게 해주는 MCP 서버입니다.

언어: TypeScript (ESM)
SDK: @modelcontextprotocol/sdk
전송: stdio
호출 제한: 1,500 call/일 (오피넷 정책)

사전 준비

오피넷 무료 API 에서 API Key 발급
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

설정 파일 위치:

OS	경로
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 방식 (가장 간편 — 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종)

Tool name	오피넷 엔드포인트	설명
`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 = 경기 광명시). 오피넷 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.

데이터 출처는 한국석유공사 오피넷이며, 데이터 사용 시 오피넷 이용 약관을 따르시기 바랍니다.

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "opinet-mcp": {
      "command": "npx",
      "args": []
    }
  }
}

Opinet

Описание

README

사전 준비

설치 & 실행 — 3가지 방법

방법 1. npx로 즉시 실행 (권장 · 별도 설치 불필요)

방법 2. 글로벌 설치

방법 3. 소스 클론 (개발 / private 사용)

MCP 클라이언트 등록

Claude Desktop / Claude Code

A. npx 방식 (가장 간편 — publish 후 사용)

B. 글로벌 설치 방식

C. 로컬 빌드 방식 (소스 클론한 경우)

다른 MCP 클라이언트 (Cursor, Cline, Continue 등)

제공 툴 (6종)

공통 코드

좌표계 주의사항

사용 예시 (자연어)

동작 확인 (스모크 테스트)

개발

배포 (npm publish)

라이선스

Как установить

Похожие MCP

GitHub

Supabase

Everything

Filesystem

Command Palette

Opinet

Описание

README

사전 준비

설치 & 실행 — 3가지 방법

방법 1. npx로 즉시 실행 (권장 · 별도 설치 불필요)

방법 2. 글로벌 설치

방법 3. 소스 클론 (개발 / private 사용)

MCP 클라이언트 등록

Claude Desktop / Claude Code

A. npx 방식 (가장 간편 — publish 후 사용)

B. 글로벌 설치 방식

C. 로컬 빌드 방식 (소스 클론한 경우)

다른 MCP 클라이언트 (Cursor, Cline, Continue 등)

제공 툴 (6종)

공통 코드

좌표계 주의사항

사용 예시 (자연어)

동작 확인 (스모크 테스트)

개발

배포 (npm publish)

라이선스

Как установить

Похожие MCP

GitHub

Supabase

Everything

Filesystem