pyth-mcp
Integrates with Pyth Network's Hermes price feed API to retrieve latest prices, confidence intervals, EMA prices, publish times, feed catalog entries, and feed metadata, including resolving symbols or feed IDs and checking API reachability.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pyth-mcp get the latest BTC/USD price with confidence and EMA"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-Aftersupport, response sizes, and MCP stdin messagesSession 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 testnpm 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 APICLI 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/projectAll 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-refreshCatalog 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 --jsonBTC 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 --jsonHistory 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 resetKey | Environment variable | Default | Meaning |
|
|
| Hermes API origin |
|
| empty | Bearer token required by current Hermes API policy |
|
|
| Per-request timeout |
|
|
| Latest-price cache TTL |
|
|
| Feed catalog cache TTL |
|
|
| 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-mcpThe 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/projectThe 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 |
| Get one latest price, confidence interval, EMA, publish time, and staleness |
| Get up to 100 prices with independent per-feed cache entries |
| Return the in-session price history for one feed |
| Search the Hermes feed catalog with optional asset and limit filters |
| Resolve a symbol or feed id to canonical feed metadata |
| Stream live price updates for up to 100 feeds for a bounded duration |
| 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 toolspyth_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
Scored across 7 tools
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.
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.
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.
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
Pyth Hermes MCP — real-time price feeds and oracle data for DeFi agents.
Unofficial Market Data App MCP — wraps the Market Data App API (marketdata.app)
Unofficial Birdeye MCP — wraps Birdeye Data Services (birdeye.so)
Historical tick, order book and settlement data for Polymarket and Predict.fun crypto up/down markets, plus smart-money lists and backtest quotes, over a read-only MCP server.
Related MCP Servers
- AlicenseBqualityBmaintenanceMCP 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.10064 npm13MIT

Chunk MCP Serverofficial
FlicenseCqualityDmaintenanceEnables querying median feeds and metrics from the Chunk network via MCP tools, including listing metrics, getting quotes, and checking contract health.14-
Orisha Data MCPofficial
AlicenseAqualityDmaintenanceClient-side MCP wrapper for Orisha Data's public x402 endpoints, providing free preview tools and paid market data access via x402 payments.7MIT
Molpha MCPofficial
AlicenseAqualityBmaintenanceMCP server for Molpha oracle data, enabling AI agents to create, fetch, verify, and publish threshold-signed oracle payloads on Solana, EVM, and Starknet.856 npm2MIT