opinet-mcp

This is an MCP server that allows you to use the Korea Petroleum Corporation's Opinet fuel price information free API in MCP clients such as Claude / Claude Code.

• Language: TypeScript (ESM)

• SDK: @modelcontextprotocol/sdk

• Transport: stdio

• Call limit: 1,500 calls/day (Opinet policy)

Prerequisites

1. Get an API Key from Opinet Free API

2. Node.js 18 or higher (uses global fetch)

Related MCP server: Korea Stats MCP

Installation & Execution — 3 Methods

Method 1. Run immediately with npx (Recommended · No separate installation required)

Available after publishing to the npm registry. See the "Deployment" section below for publishing.

OPINET_API_KEY=발급키 npx -y opinet-mcp

Method 2. Global installation

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

Method 3. Clone source (For development / private use)

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 Registration

Claude Desktop / Claude Code

Configuration file location:

A. npx method (Easiest — use after publishing)

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

B. Global installation method

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

C. Local build method (If source is cloned)

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

⚠️ Claude Desktop has limited inheritance of PATH. If it cannot find the command when running with command: "node" or "npx", specify the absolute path (e.g., /opt/homebrew/bin/node, /usr/local/bin/npx). Check with which node / which npx in the terminal.

After configuration, completely quit Claude Desktop (Cmd+Q) → Relaunch, and you will see 6 tools in the tool icon.

Other MCP Clients (Cursor, Cline, Continue, etc.)

You can add it to the MCP server configuration file of each client in the same way as the JSON structure above.

Provided Tools (6 types)

Common Codes

Product Code (prodcd)

Province Code (sido / area 2 digits)

The city/county/district unit is a 4-digit code (e.g., 0207 = Gyeonggi Gwangmyeong-si). Can be queried separately via the Opinet areaCode.do endpoint.

Coordinate System Notes

The input coordinates (x, y) for search_stations_around and the GIS_X_COOR / GIS_Y_COOR in all responses are in the KATEC coordinate system. They are different from WGS84 (latitude/longitude), so if you want to receive latitude/longitude as input, convert them to KATEC in the client before calling.

Usage Examples (Natural Language)

• "Tell me today's national average gasoline price" → get_national_average_price

• "Average diesel price in Seoul" → get_sido_average_price (sido=01, prodcd=D047)

• "Gasoline trend for the last 7 days" → get_recent_7days_price (prodcd=B027)

• "5 cheapest gas stations for gasoline in Gwangmyeong-si" → get_lowest_price_top20 (prodcd=B027, area=0207, cnt=5)

• "Detailed info for gas station ID A0008322" → get_station_detail

Verification (Smoke Test)

Run without an API key → If it guides you to environment variables and exits, the build is OK:

node dist/index.js

When you have an API key, call directly via 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

Development

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

Project structure:

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

Deployment (npm publish)

When publishing for the first time:

# 1) npm 로그인
npm login

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

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

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

Version update afterwards:

npm version patch   # 0.1.0 -> 0.1.1
npm publish

After publishing, anyone can use it immediately with npx -y opinet-mcp.

There is a prepare script, so it builds automatically upon npm install. This means it also works if installed directly from GitHub (npm i github:KimJintak/opinet-mcp).

License

MIT.

The data source is the Korea Petroleum Corporation Opinet, and please follow the Opinet Terms of Service when using the data.