opinet-mcp

Este es un servidor MCP que permite utilizar la API gratuita de información de precios de combustible Opinet de la Korea Petroleum Corporation en clientes MCP como Claude / Claude Code.

• Lenguaje: TypeScript (ESM)

• SDK: @modelcontextprotocol/sdk

• Transporte: stdio

• Límite de llamadas: 1,500 llamadas/día (política de Opinet)

Preparación

1. Obtenga una clave API en Opinet Free API

2. Node.js 18 o superior (utiliza fetch global)

Instalación y ejecución — 3 métodos

Método 1. Ejecución inmediata con npx (recomendado · no requiere instalación)

Disponible tras publicar en el registro npm. Consulte la sección "Distribución" a continuación.

OPINET_API_KEY=발급키 npx -y opinet-mcp

Método 2. Instalación global

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

Método 3. Clonar el código fuente (para desarrollo / uso privado)

git clone https://github.com/KimJintak/opinet-mcp.git
cd opinet-mcp
npm install
npm run build
OPINET_API_KEY=발급키 node dist/index.js

Registro en el cliente MCP

Claude Desktop / Claude Code

Ubicación del archivo de configuración:

A. Método npx (el más sencillo — usar tras publicar)

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

B. Método de instalación global

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

C. Método de compilación local (si clonó el código fuente)

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

⚠️ Claude Desktop hereda el PATH de forma limitada. Si no encuentra el comando al usar command: "node" o "npx", especifique la ruta absoluta (/opt/homebrew/bin/node, /usr/local/bin/npx, etc.). Verifique con which node / which npx en la terminal.

Tras configurar, cierre completamente Claude Desktop (Cmd+Q) y reinícielo para ver las 6 herramientas en el icono de herramientas.

Otros clientes MCP (Cursor, Cline, Continue, etc.)

Puede añadir la configuración siguiendo la misma estructura JSON en el archivo de configuración del servidor MCP de cada cliente.

Herramientas disponibles (6 tipos)

Códigos comunes

Código de producto (prodcd)

Código de provincia (sido / area 2 dígitos)

La unidad de ciudad/distrito utiliza un código de 4 dígitos (ej: 0207 = Gyeonggi Gwangmyeong-si). Se puede consultar por separado mediante el endpoint areaCode.do de Opinet.

Notas sobre el sistema de coordenadas

Las coordenadas de entrada (x, y) para search_stations_around y los valores GIS_X_COOR / GIS_Y_COOR de todas las respuestas están en el sistema de coordenadas KATEC. Como es diferente de WGS84 (latitud/longitud), si desea recibir latitud/longitud como entrada, conviértalas a KATEC en el cliente antes de realizar la llamada.

Ejemplos de uso (lenguaje natural)

• "Dime el precio promedio nacional de la gasolina hoy" → get_national_average_price

• "Precio promedio del diésel en Seúl" → get_sido_average_price (sido=01, prodcd=D047)

• "Tendencia de la gasolina en los últimos 7 días" → get_recent_7days_price (prodcd=B027)

• "Las 5 gasolineras con la gasolina más barata en Gwangmyeong-si" → get_lowest_price_top20 (prodcd=B027, area=0207, cnt=5)

• "Detalles de la gasolinera con ID A0008322" → get_station_detail

Verificación de funcionamiento (prueba de humo)

Ejecutar sin clave API → Si muestra la guía de variables de entorno y termina, la compilación es correcta:

node dist/index.js

Si tiene una clave API, llame directamente a través de 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

Desarrollo

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

Estructura del proyecto:

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

Distribución (npm publish)

Al publicar por primera vez:

# 1) npm 로그인
npm login

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

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

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

Actualizaciones de versión:

npm version patch   # 0.1.0 -> 0.1.1
npm publish

Tras la publicación, cualquiera puede usarlo inmediatamente con npx -y opinet-mcp.

Incluye un script prepare, por lo que se compila automáticamente al ejecutar npm install. Es decir, también funciona instalándolo directamente desde GitHub (npm i github:KimJintak/opinet-mcp).

Licencia

MIT.

La fuente de los datos es Opinet de la Korea Petroleum Corporation; al utilizar los datos, por favor cumpla con los Términos de servicio de Opinet.