Skip to main content
Glama

pyth-mcp

Pyth Network Hermes price feeds with a feed catalog, exact exponent handling, confidence intervals, EMA prices, TTL caching, price history, live streaming, a CLI, and an MCP stdio server. The implementation uses only Node.js built-ins and has no install scripts.

Frequently asked questions

Works with Claude Desktop, Cursor, Windsurf and any MCP client.

How do I get Pyth oracle prices in Claude Desktop?

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "pyth-mcp": {
      "command": "npx",
      "args": ["-y", "pyth-mcp"]
    }
  }
}

Then ask Claude for live prices, feed catalogs, or price history.

What is the best free price feed MCP server for AI agents?

pyth-mcp gives you Pyth Network Hermes price feeds over MCP: live prices with confidence intervals, EMA prices, a feed catalog, TTL caching, and price history — all with zero runtime dependencies.

How do I track real-time crypto prices with MCP?

Use the pyth-mcp CLI (pyth-mcp price BTC/USD) or the MCP tools (pyth_get_prices, pyth_list_feeds). Prices come from Pyth Network Hermes with exact exponent handling and confidence intervals.

How to build a price alert bot with Pyth?

Run pyth-mcp watch BTC/USD --above 100000 --below 60000 — the CLI prints alerts only when a threshold is crossed. For programmatic use, the client library exposes the same watch loop.

Does pyth-mcp need an API key?

No. Pyth Network Hermes is a public price feed API — pyth-mcp works out of the box with no API key and no account.

Can I get price history and stale prices?

Yes. pyth_get_price_history returns a bounded time series per feed, and --allow-stale returns the last known value with a stale: true flag when a fresh update is unavailable.

Related MCP server: Chunk MCP Server

Properties

  • Node.js 20 or newer; zero runtime dependencies

  • Latest Pyth prices with raw integer values, exact decimal text, exponent, confidence interval, EMA price, publish time, staleness, and metadata

  • Feed resolution by symbol, base asset, or 64-character hexadecimal feed id

  • Built-in mappings for BTC/USD, ETH/USD, SOL/USD, USDC/USD, and USDT/USD

  • Hermes catalog search for all other supported Pyth feeds and asset types

  • Per-feed price cache and query-specific catalog cache persisted on disk

  • Self-healing cache: corrupt cache files are quarantined and rebuilt

  • Expiration pruning, 1,000-entry and 8 MiB cache limits, and batched writes

  • Bounded timeouts, retries with Retry-After support, response sizes, and MCP stdin messages

  • Session price history with bounded ring buffers

  • Stale-while-revalidate fallback on refresh failures

  • Seven MCP tools with closed JSON Schemas and JSON-RPC 2.0 notifications

  • TypeScript type declarations for the programmatic API

  • Deterministic offline tests plus optional live Hermes and packed-artifact tests

Install and verify

npm install pyth-mcp
npm test

npm test uses a local mock Hermes server and requires no external network. Additional verification commands are:

npm run test:packed   # pack, install with scripts disabled, and execute
npm run test:live     # query the public Hermes API

CLI quick start

pyth-mcp init --root /path/to/project
pyth-mcp list-prices BTC --root /path/to/project
pyth-mcp get-price BTC/USD --root /path/to/project
pyth-mcp get-price BTC/USD,ETH/USD --json --root /path/to/project
pyth-mcp history BTC/USD --limit 20 --root /path/to/project
pyth-mcp watch SOL/USD --interval 5000 --count 10 --root /path/to/project
pyth-mcp watch BTC/USD --above 70000 --below 60000 --json --root /path/to/project
pyth-mcp mcp-start --root /path/to/project

All commands accept --root DIR; it defaults to the current directory. State is stored under .pyth-mcp/. Use --json for machine-readable output. Watch mode always fetches fresh updates and emits one result per polling interval; --count 0 continues until interrupted. Watch survives transient network failures by printing an error record and continuing on the next interval. With --above or --below, watch emits an ALERT line only when the price crosses the given threshold.

Feed catalog

pyth-mcp list-prices
pyth-mcp list-prices ETH
pyth-mcp list-prices AAPL --asset-type equity
pyth-mcp list-prices USD --limit 100 --force-refresh

Catalog results include the feed id, full symbol, base and quote currencies, asset type, and description. The default catalog TTL is one hour. An empty query returns the first 50 catalog entries after client-side sorting. Invalid individual catalog entries are skipped and reported in skipped instead of failing the whole request.

Latest prices

pyth-mcp get-price BTC
pyth-mcp get-price ETH/USD --force-refresh
pyth-mcp get-price e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43
pyth-mcp get-price BTC/USD,ETH/USD,SOL/USD --cache-ttl 60 --json
pyth-mcp get-price BTC/USD --allow-stale --json

BTC and other built-in base symbols resolve to their USD feed. For other assets, use a full catalog symbol when a base symbol is ambiguous. Cached responses retain the original fetchedAt and set cached: true. A TTL of zero disables price cache reads and writes for that request. Batch calls return successful quotes in prices and per-feed failures in errors; a batch throws only when no requested price can be returned.

Every quote carries staleness information: stalenessSeconds measures the age of the oracle update relative to the local clock, and stale: true marks updates older than 60 seconds. With --allow-stale, a failed refresh falls back to the last known quote and marks it stale: true with staleSource: 'history'.

Price history

pyth-mcp history BTC/USD --root /path/to/project
pyth-mcp history ETH/USD --limit 5 --json

History records every fresh quote fetched during the current session in a bounded ring buffer (1,000 entries per feed by default) and returns them newest last. History is in-memory only and never written to disk.

Configuration

pyth-mcp config
pyth-mcp config get cacheTtlMs
pyth-mcp config set cacheTtlMs 60000
pyth-mcp config set baseUrl https://hermes.pyth.network
pyth-mcp config reset

Key

Environment variable

Default

Meaning

baseUrl

PYTH_BASE_URL

https://hermes.pyth.network

Hermes API origin

apiKey

PYTH_API_KEY

empty

Bearer token required by current Hermes API policy

timeoutMs

PYTH_TIMEOUT_MS

10000

Per-request timeout

cacheTtlMs

PYTH_CACHE_TTL_MS

30000

Latest-price cache TTL

catalogTtlMs

PYTH_CATALOG_TTL_MS

3600000

Feed catalog cache TTL

retries

PYTH_RETRIES

2

Retries for 429, 5xx, and network errors

PYTH_ROOT selects the project root when --root is not provided. Environment values override the config file; explicit programmatic overrides take highest precedence. URLs must use HTTP or HTTPS and cannot contain credentials. The API key is sent only as Authorization: Bearer ...; CLI and public config output redact it. Set PYTH_API_KEY before live price retrieval because Pyth now requires an API key for Hermes price updates.

When Hermes responds with 429 Too Many Requests, the client honors the Retry-After header (seconds or HTTP date) before retrying, bounded by the retry backoff and a 60-second cap.

If the on-disk cache becomes unreadable, it is renamed to cache.json.corrupt-<timestamp> and the cache restarts empty; a corrupt cache never prevents startup.

Docker

Build and run the MCP server in a container:

docker build -t pyth-mcp .
docker run -i --rm pyth-mcp

The container runs the MCP stdio server directly, so any MCP client can use it as a containerized command.

MCP server

pyth-mcp mcp-start --root /path/to/project

The server speaks newline-delimited JSON-RPC 2.0 over stdio and reserves stdout for protocol messages. It negotiates MCP 2025-06-18, 2025-03-26, or 2024-11-05. Notifications receive no response. Duplicate initialize requests are rejected. The latest protocol rejects batch requests; older negotiated versions support JSON-RPC batch arrays.

Tools

Tool

Purpose

pyth_get_price

Get one latest price, confidence interval, EMA, publish time, and staleness

pyth_get_prices

Get up to 100 prices with independent per-feed cache entries

pyth_get_price_history

Return the in-session price history for one feed

pyth_list_feeds

Search the Hermes feed catalog with optional asset and limit filters

pyth_resolve_feed

Resolve a symbol or feed id to canonical feed metadata

pyth_stream_prices

Stream live price updates for up to 100 feeds for a bounded duration

pyth_ping

Check Hermes reachability with a small live request

All tools have closed input schemas. Schema violations return -32602. Domain failures such as an unknown feed, timeout, or upstream API error are returned as tool results with isError: true and a structured error code.

pyth_stream_prices subscribes to the Hermes streaming endpoint and collects Server-Sent Events price updates for duration_ms (default 30000, maximum 300000) or until max_updates (default 100, maximum 1000) arrive, then returns the collected updates. Streaming talks only to the configured Hermes origin.

Programmatic API

const { PythClient } = require('pyth-mcp');

const client = new PythClient({ rootDir: process.cwd() });
const feed = await client.resolveFeed('BTC/USD');
const quote = await client.getPrice(feed.id);
const batch = await client.getPrices(['BTC/USD', 'ETH/USD']);
const catalog = await client.listFeeds({ query: 'SOL', limit: 10 });
const history = await client.getPriceHistory('BTC/USD', { limit: 20 });
const stream = await client.streamPrices(['BTC/USD'], { durationMs: 5000 });
client.close();

Price values are available both as JavaScript numbers and exact decimal text. The original integer strings remain under raw, so consumers do not need to reconstruct values from floating-point numbers.

TypeScript users can import the bundled declarations directly:

import { PythClient, PriceUpdate } from 'pyth-mcp';

Pyth data is subject to Pyth Network's terms and Hermes rate limits. This package retrieves oracle data only; it does not provide financial advice, trading execution, or on-chain transaction submission.

Available Tools

7 tools
pyth_get_priceB

Get the latest Pyth price, confidence interval, EMA price, exponent, publish time, and staleness for one symbol or feed id.

Inputs: feed (required), cache_ttl, allow_stale, force_refresh.

pyth_get_price_historyA

Return the in-memory price history recorded during this session for one symbol or feed id, newest last.

Inputs: feed (required), limit.

pyth_get_pricesC

Get latest Pyth prices for up to 100 symbols or feed ids, using independent per-feed cache entries.

Inputs: feeds (required), cache_ttl, allow_stale, force_refresh.

pyth_list_feedsB

Search the Pyth Hermes price feed catalog by symbol or description, with a one-hour catalog cache by default.

Inputs: limit, query, asset_type, force_refresh.

pyth_pingA

Check Pyth Hermes API reachability with a small live feed catalog request.

Inputs: no named parameters.

pyth_resolve_feedA

Resolve a symbol such as BTC/USD or a 64-character hexadecimal id to canonical Pyth feed metadata.

Inputs: feed (required).

pyth_stream_pricesB

Stream live Pyth price updates from the Hermes streaming endpoint for up to 100 feeds, collecting updates for a bounded duration.

Inputs: feeds (required), threshold, duration_ms, max_updates.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: single latest price, batch latest prices, session price history, streaming updates, catalog search, feed resolution, and API ping. The single-vs-batch-vs-history-vs-stream boundaries are explicit in the descriptions, so an agent can select the right tool without ambiguity.

    Naming Consistency4/5

    All tools use a consistent pyth_ prefix followed by mostly verb_noun names such as get_price, list_feeds, resolve_feed, and stream_prices. The only minor deviation is pyth_ping, which lacks a noun component, but it is still readable and conventional.

    Tool Count5/5

    Seven tools is a well-scoped surface for a Pyth price-feed MCP server. Each operation covers a meaningful capability without redundant variants or excessive fragmentation.

    Completeness4/5

    The set covers reachability, feed discovery/resolution, latest single and batch prices, session history, and bounded streaming, which handles the core data-retrieval workflows. A minor gap is that historical prices are only session-recorded rather than queryable from a broader Hermes time range.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      MCP server for querying historical and real-time crypto market data across Hyperliquid, Hyperliquid HIP-3, and Lighter.xyz - orderbooks, trades, candles, funding, open interest, liquidations, and data quality metrics.
      100
      64 npm
      13
      MIT
    • F
      license
      C
      quality
      D
      maintenance
      Enables querying median feeds and metrics from the Chunk network via MCP tools, including listing metrics, getting quotes, and checking contract health.
      14
      -
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Molpha oracle data, enabling AI agents to create, fetch, verify, and publish threshold-signed oracle payloads on Solana, EVM, and Starknet.
      8
      56 npm
      2
      MIT