Gas Price Check, Cheapest Gas Near You

What you get

Six tools that let AI agents answer questions like:

What is the cheapest gas near ZIP 77386 right now?
Which US state has the cheapest gas this week?
How have Illinois gas prices moved over the last 14 days?
Where are the Buc-ee's locations in Texas?

Available tools

Tool	Description	Arguments
find_brand_locations	Look up gas stations for a major US fuel brand (Buc-ee's, Costco, Sam's Club). Optionally filter by state.	brand (required), state (optional)
get_national_average	Current US national average retail gasoline price from EIA.	none
get_state_average	Current average gas price for a US state. Falls back to PADD region for states without their own EIA series.	state_code (required)
compare_states	Compare current gas prices across up to 10 US states. Ranked cheapest to most expensive.	state_codes (required, max 10)
get_price_trend	Day-by-day gas-price trend for a state over the last N days (max 30). Unique capability. Most public APIs only expose the freshest value.	state_code (required), days (optional, default 14)
get_gas_prices_by_zip	Top stations near a ZIP code, sorted by price. Cache-only: returns a warmup hint if the ZIP has not been queried recently from the website.	zip (required), fuel_type (optional), limit (optional)

Connecting Claude.ai (web)

In a Claude.ai conversation, open Settings → Connectors → Add custom connector and paste this URL:

https://www.gas-price-check.com/api/mcp

Authentication: none required. The connector will list the six tools immediately and Claude can call them from any conversation.

Connecting Claude Desktop

Edit your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this entry under mcpServers:

{
  "mcpServers": {
    "gas-price-check": {
      "url": "https://www.gas-price-check.com/api/mcp"
    }
  }
}

Restart Claude Desktop. The tools appear in the connector menu (paperclip icon).

Connecting Cursor

Open Settings → MCP → Add new MCP server. Use type http and the same URL above. Cursor picks up the tool list on next chat turn.

Connecting any other MCP client

This server speaks standard JSON-RPC 2.0 over HTTP POST to /api/mcp. It implements the MCP initialize, tools/list, and tools/call methods. Protocol version 2024-11-05. Any compliant client should connect with no configuration beyond the URL.

Data sources and freshness

State + national averages: US Energy Information Administration (EIA) weekly retail series, cached for 24 hours. EIA refreshes Mondays around 1pm ET.
Price history snapshots: daily snapshot of each state's EIA value to our database. Returns up to 30 days of history.
Station-level prices by ZIP: sourced from station-level providers, cached for 24 hours. Cache is warmed by organic website traffic.
Brand locations: curated list of Buc-ee's, Costco, and Sam's Club locations. Updated manually.

Cache-only mode (why some ZIPs return a hint)

get_gas_prices_by_zip reads our cache. If the ZIP has not been queried from the website recently, the tool returns:

{
  "zip": "...",
  "cache_status": "miss",
  "data": null,
  "hint": "Visit https://www.gas-price-check.com/<zip> to warm the cache"
}

This is intentional. Triggering on-demand scrapes from MCP calls would expose us to abuse (an agent enumerating every US ZIP would cost hundreds of dollars in data fees). Cache-only mode means the tool is free to operate. To get fresh data for a specific ZIP, visit the site URL once and the cache will be warm for 24 hours.

Rate limits

30 requests per IP per minute. Enforced at the edge.
Hitting the limit returns HTTP 429 and a short cooldown. Back off and retry with exponential delay.
compare_states is capped at 10 state codes per call. get_price_trend is capped at 30 days. These are per-call limits, not rate limits.

Attribution

If your application surfaces results from this MCP server to end users, a link back to gas-price-check.com is appreciated but not required. We log no PII; tool calls are logged at the aggregate level for quota and observability.

Roadmap

City-level lookups (currently requires knowing the ZIP)
Brand price comparisons across states
Diesel and EV charging price tools
Paid tier with fresher data and higher rate limits, if demand emerges

Feature requests: @gaspricecheck on X.