oil-price-mcp

一个可通过 npx 直接启动的 stdio MCP 服务，用于查询中国省份油价，并支持“城市 -> 省份”自动映射。适合发布到 npm 后，在支持 npx 的 MCP 托管平台或客户端中直接接入。

功能

• 按省份查询今日油价
• 按城市自动映射到所属省份后查询
• 使用环境变量 MXNZP_APP_ID、MXNZP_APP_SECRET
• 返回稳定 JSON 结构，方便后续做推送或展示

环境要求

• Node.js 20+
• 已申请 MXNZP 的 app_id / app_secret

本地开发

安装依赖：

npm install

设置环境变量后启动：

set MXNZP_APP_ID=你的_app_id
set MXNZP_APP_SECRET=你的_app_secret
npm run dev

构建

npm run build

作为 stdio MCP 使用

本地直接运行：

npx oil-price-mcp

或者在支持 command / args / env 的 MCP 配置里这样写：

{
  "mcpServers": {
    "oil-price": {
      "command": "npx",
      "args": [
        "-y",
        "oil-price-mcp"
      ],
      "env": {
        "MXNZP_APP_ID": "你的_app_id",
        "MXNZP_APP_SECRET": "你的_app_secret"
      }
    }
  }
}

这正好适合你截图里的 npx 托管界面。

ModelScope 自定义 MCP 示例

如果平台要求填“服务配置”，直接填：

{
  "mcpServers": {
    "oil-price": {
      "command": "npx",
      "args": [
        "-y",
        "oil-price-mcp"
      ],
      "env": {
        "MXNZP_APP_ID": "你的_app_id",
        "MXNZP_APP_SECRET": "你的_app_secret"
      }
    }
  }
}

安装命令选 npx。

可用工具

get_oil_price_by_province

输入：

{
  "province": "广东"
}

get_oil_price_by_city

输入：

{
  "city": "深圳"
}

list_supported_provinces

返回当前支持的省份列表。

get_deployment_info

返回当前服务的运行模式、所需环境变量和上游接口地址。

返回格式说明

工具会返回一段摘要文本，并附带 JSON 文本。核心字段如下：

{
  "queryType": "city",
  "queryValue": "深圳",
  "normalizedProvince": "广东",
  "normalizedCity": "深圳",
  "prices": {
    "t0": "7.64",
    "t89": "7.42",
    "t92": "7.99",
    "t95": "8.65",
    "t98": "9.79"
  },
  "fetchedAt": "2026-03-14T11:22:33.000Z",
  "source": {
    "provider": "mxnzp",
    "endpoint": "https://www.mxnzp.com/api/oil/search",
    "message": "数据返回成功！"
  }
}

测试

npm test

发布到 npm

先确认登录：

npm whoami

预览发布内容：

npm pack --dry-run

正式发布：

npm publish --access public

当前限制

• 城市映射基于内置表，优先覆盖常见城市和主要地级市
• 如果某个城市暂未收录，请直接传省份名称，或后续补充映射表