opinet-mcp

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

• 언어: TypeScript (ESM)

• SDK: @modelcontextprotocol/sdk

• 전송: stdio

• 호출 제한: 1,500 call/일 (오피넷 정책)

사전 준비

1. 오피넷 무료 API 에서 API Key 발급

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 = 경기 광명시). 오피넷 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.

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