pyth-network-mcp by itsOmSarraf - MCP Server

Pyth Network MCP Server

An MCP server that provides real-time access to Pyth Network's decentralized oracle price feeds via the Hermes API, optimized for seamless integration into AI agents and autonomous systems.

Author: @itsomsarraf

Features

🔧 Tools (5 Available)

Search Price Feeds: Search and filter through 1,930+ price feeds by symbol or asset type across 107+ blockchains
Get Latest Prices: Fetch real-time price updates for specific price feed IDs with parsed data (no binary clutter)
Historical Price Data: Query price updates at specific timestamps for backtesting and analysis
Publisher Stake Caps: Access the latest publisher stake caps data from the Pyth network
Time-Weighted Average Prices (TWAP): Calculate TWAP with custom time windows (1-600 seconds) for more stable pricing

💬 Prompts (4 Available)

Analyze Price Feed: Get detailed analysis of any asset with current price, TWAP, and volatility metrics
Compare Prices: Side-by-side comparison of multiple assets with volatility analysis
Market Overview: Comprehensive market report for any asset type (crypto, equity, fx, metal, rates)
Price Alert Setup: Step-by-step guidance for setting up price monitoring systems

📚 Resources (3 Available)

Pyth Network Information: Overview of the network, data providers, and capabilities
Popular Price Feeds: Quick reference of commonly used price feed IDs for major assets
API Documentation Reference: Quick reference guide for Hermes API endpoints

🌐 Universal Features

Universal Price Feed IDs: Unlike chain-specific oracles, Pyth uses universal price feed IDs that work across all supported blockchains
Full MCP Compliance: Implements tools, prompts, and resources according to MCP specification

Supported Asset Types and Coverage

Pyth Network aggregates data from 125+ first-party financial institutions, including major exchanges, market makers, and trading firms, providing:

1,930+ Price Feeds across 107+ Blockchains
Asset Types:
- crypto - Cryptocurrencies (BTC/USD, ETH/USD, SOL/USD, etc.)
- equity - Traditional equities and stocks
- fx - Foreign exchange pairs
- metal - Precious metals (Gold, Silver, etc.)
- rates - Interest rates and rate products

Pyth operates on a pull-based oracle model, delivering high-frequency price updates (refreshed every ~400ms) directly from data providers to smart contracts across multiple chains including Ethereum, Solana, Avalanche, BNB Chain, Aptos, Sui, Near, and many more.

Prerequisites

Python: Version 3.10 or higher
Package Manager: pip or uv (recommended)
Claude Desktop (optional): For integration with Anthropic's Claude interface
Cursor/Windsurf (optional): For IDE integration

Installation

Clone the Repository

git clone https://github.com/itsomsarraf/pyth-network-mcp.git
cd pyth-network-mcp

Install Dependencies

Using uv (recommended):

uv sync

Using pip:

pip install mcp httpx

The project requires:

mcp>=1.0.0 - Official MCP SDK
httpx>=0.27.0 - For HTTP requests to Pyth Hermes API

Configure MCP Client

To use this server with an MCP client like Claude Desktop, add the following to your MCP settings configuration file:

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "pyth-network": {
      "command": "python3",
      "args": ["pyth_mcp_server.py"],
      "cwd": "/absolute/path/to/pyth-network-mcp"
    }
  }
}

For Cursor/Windsurf (.cursorrules or MCP settings):

{
  "mcpServers": {
    "pyth-network": {
      "command": "python3",
      "args": ["pyth_mcp_server.py"],
      "cwd": "/absolute/path/to/pyth-network-mcp"
    }
  }
}

Using uv:

{
  "mcpServers": {
    "pyth-network": {
      "command": "uv",
      "args": ["run", "pyth_mcp_server.py"],
      "cwd": "/absolute/path/to/pyth-network-mcp"
    }
  }
}

Running the Server

The server uses stdio transport (standard input/output) for MCP communication:

python3 pyth_mcp_server.py

To test the server with the included client:

python3 pyth_mcp_client.py

Usage

The server exposes 5 tools, 4 prompts, and 3 resources via the MCP protocol, accessible through Claude Desktop (for natural language queries), Cursor/Windsurf, or programmatically.

MCP Capabilities Overview

Capability	Count	Description
Tools	5	Direct API interactions for getting price data
Prompts	4	Pre-configured analysis templates for common tasks
Resources	3	Static reference information and documentation

Below are detailed descriptions of each capability with examples.

Tool: `get_price_feeds`

Description: Search and filter price feeds from the Pyth network by symbol or asset type. This is useful for discovering available price feeds before querying their prices.

Parameters:

query (string, optional): Filter results to price feeds whose symbol contains this string (case insensitive). Example: "bitcoin", "eth", "gold"
asset_type (string, optional): Filter by asset type (case insensitive). Options: crypto, equity, fx, metal, rates

Returns: List of price feed metadata with IDs and attributes.

Natural Language Example (Claude Desktop):

User: "What Bitcoin price feeds are available?"

Assistant: "I found several Bitcoin price feeds including:

BTC/USD (ID: e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43)

BTC/ETH

BTC/EUR

These feeds are available across all 107+ supported blockchains."

Example JSON Response:

{
  "price_feeds": [
    {
      "id": "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43",
      "attributes": {
        "symbol": "Crypto.BTC/USD",
        "asset_type": "Crypto",
        "base": "BTC",
        "quote_currency": "USD",
        "description": "Bitcoin vs US Dollar"
      }
    }
  ]
}

Tool: `get_latest_price_updates`

Description: Fetch the latest price updates for specific price feed IDs. Returns clean, readable price data without binary clutter.

Parameters:

ids (list[string], required): List of price feed IDs to get updates for
encoding (string, optional): Encoding type for binary data. Options: hex, base64. Default: hex
parsed (boolean, optional): If true, include parsed price data. Default: true
ignore_invalid_price_ids (boolean, optional): If true, invalid price IDs are ignored. Default: false
include_binary (boolean, optional): If true, include binary data. Default: false (clean output)

Returns: Price updates with parsed, human-readable data.

Natural Language Example (Claude Desktop):

User: "What's the current price of Bitcoin in USD?"

Assistant: "The current BTC/USD price is $113,395.22 (as of 2 seconds ago). The price has a confidence interval of ±$234.77."

Example JSON Response:

{
  "parsed": [
    {
      "id": "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43",
      "price": {
        "price": "11339522000000",
        "conf": "23477142598",
        "expo": -8,
        "publish_time": 1760133288
      },
      "ema_price": {
        "price": "11620589900000",
        "conf": "7599704800",
        "expo": -8,
        "publish_time": 1760133288
      },
      "metadata": {
        "slot": 247985552,
        "proof_available_time": 1760133290,
        "prev_publish_time": 1760133288
      }
    }
  ]
}

Note: The price value must be multiplied by 10^expo to get the actual price. Example: 11339522000000 × 10^-8 = $113,395.22

Tool: `get_price_updates_at_time`

Description: Get historical price updates at or after a specific timestamp. This is useful for backtesting strategies or analyzing historical price movements.

Parameters:

publish_time (integer, required): Unix timestamp in seconds
ids (list[string], required): List of price feed IDs to get updates for
encoding (string, optional): Encoding type for binary data. Options: hex, base64. Default: hex
parsed (boolean, optional): If true, include parsed price data. Default: true
ignore_invalid_price_ids (boolean, optional): If true, invalid price IDs are ignored. Default: false
include_binary (boolean, optional): If true, include binary data. Default: false

Returns: Price updates at or after the specified timestamp.

Natural Language Example (Claude Desktop):

User: "What was the BTC/USD price at timestamp 1760132736?"

Assistant: "At timestamp 1760132736, the BTC/USD price was $112,103.54 with a confidence interval of ±$869.53."

Example JSON Response:

{
  "parsed": [
    {
      "id": "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43",
      "price": {
        "price": "11210354370540",
        "conf": "86953286118",
        "expo": -8,
        "publish_time": 1760132736
      },
      "ema_price": {
        "price": "11629198600000",
        "conf": "6729670300",
        "expo": -8,
        "publish_time": 1760132736
      },
      "metadata": {
        "slot": 247984264,
        "proof_available_time": 1760132737,
        "prev_publish_time": 1760132735
      }
    }
  ]
}

Tool: `get_publisher_stake_caps`

Description: Get the most recent publisher stake caps update data. This provides information about publisher staking limits in the Pyth network, which is important for understanding network security and data quality.

Parameters:

encoding (string, optional): Encoding type for binary data. Options: hex, base64. Default: hex
parsed (boolean, optional): If true, include parsed update data. Default: true
include_binary (boolean, optional): If true, include binary data. Default: false

Returns: Latest publisher stake caps update data in parsed, readable format.

Natural Language Example (Claude Desktop):

User: "What are the current publisher stake caps on the Pyth network?"

Assistant: "The latest publisher stake caps data shows staking limits for each publisher in the network. This includes caps for all 125+ data providers, with the highest cap being 87.4 trillion units."

Example JSON Response:

{
  "parsed": [
    {
      "publisher_stake_caps": [
        {
          "publisher": "7YQg8Tz9KHKsg7yHiAFRBsDkLoKvZbMXt7VbW44F7QM",
          "cap": 87415862629839
        },
        {
          "publisher": "8Mg3RA4aNRzw68pZKjB3rsBJ7gB3UDcFwKBbiXLnhHX",
          "cap": 54545454545
        }
      ]
    }
  ]
}

Tool: `get_twap_latest`

Description: Get the latest Time-Weighted Average Price (TWAP) with a custom time window. TWAP provides more stable pricing by averaging prices over time, which is useful for reducing the impact of short-term volatility.

Parameters:

window_seconds (integer, required): Time window in seconds (1-600). Example: 60 = 1 minute TWAP, 300 = 5 minute TWAP
ids (list[string], required): List of price feed IDs to get TWAP for
encoding (string, optional): Encoding type for binary data. Options: hex, base64. Default: hex
parsed (boolean, optional): If true, include calculated TWAP in parsed field. Default: true
ignore_invalid_price_ids (boolean, optional): If true, invalid price IDs are ignored. Default: false
include_binary (boolean, optional): If true, include binary data. Default: false

Returns: Time-weighted average prices for the specified window.

Natural Language Example (Claude Desktop):

User: "What's the 5-minute TWAP for BTC/USD?"

Assistant: "The 5-minute TWAP for BTC/USD is $113,318.45, which is slightly lower than the current spot price of $113,395.22. This indicates recent upward price movement."

Example JSON Response:

{
  "parsed": [
    {
      "id": "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43",
      "start_timestamp": 1760132736,
      "end_timestamp": 1760133036,
      "twap": {
        "price": "11331845299185",
        "conf": "48677830724",
        "expo": -8,
        "publish_time": 1760133036
      },
      "down_slots_ratio": "0"
    }
  ]
}

Prompts

Prompts are pre-configured templates that guide AI assistants through complex multi-step tasks.

Prompt: `analyze_price_feed`

Description: Get a detailed analysis of any asset including current price, TWAP, confidence intervals, and volatility metrics.

Arguments:

asset_symbol (required): Symbol of the asset to analyze (e.g., BTC, ETH, SOL)

Example Usage in Claude Desktop:

User: "Use the analyze_price_feed prompt for ETH"

Claude: Executes multi-step analysis including:

Searches for ETH price feeds

Gets latest price

Calculates 5-minute TWAP

Provides comprehensive analysis with trends

Prompt: `compare_prices`

Description: Compare multiple assets side by side with price, TWAP, and volatility analysis.

Arguments:

symbols (required): Comma-separated list of asset symbols (e.g., BTC,ETH,SOL)

Example Usage:

"Use the compare_prices prompt with symbols BTC,ETH,SOL"

Creates a comparison table showing relative performance and volatility.

Prompt: `market_overview`

Description: Generate a comprehensive market report for a specific asset type.

Arguments:

asset_type (required): crypto, equity, fx, metal, or rates

Example Usage:

"Use the market_overview prompt for crypto assets"

Provides overview of all crypto feeds with prices and trends.

Prompt: `price_alert_setup`

Description: Get step-by-step instructions for setting up automated price monitoring.

Arguments:

asset_symbol (required): Symbol of the asset to monitor

Example Usage:

"Use the price_alert_setup prompt for SOL"

Provides feed ID, current price, polling recommendations, and code examples.

Resources

Resources provide static reference information about Pyth Network.

Resource: `pyth://network/info`

Content: General information about Pyth Network

Network overview
125+ data providers
Coverage statistics (1,930+ feeds, 107+ chains)
Key features and capabilities

Access in Claude Desktop: "Show me the Pyth Network information resource"

Resource: `pyth://feeds/popular`

Content: JSON reference of popular price feed IDs

Top crypto pairs (BTC/USD, ETH/USD, SOL/USD, etc.)
Major equities (AAPL, TSLA, MSFT)
FX pairs (EUR/USD, GBP/USD)
Precious metals (Gold, Silver)

Access: "Show me popular Pyth price feeds"

Resource: `pyth://docs/api`

Content: Quick reference for Hermes API

All endpoint documentation
Query parameter formats
Price format explanation
Example requests

Access: "Show me the Pyth API documentation resource"

Testing the Server

The repository includes a demonstration client (pyth_mcp_client.py) that shows how to use all five tools with the official MCP protocol. Run it with:

python3 pyth_mcp_client.py

Finding Price Feed IDs

To find the correct price feed ID for your desired asset:

Use the get_price_feeds tool to search by symbol:
```
"Search for Ethereum price feeds"
```
Or visit the Pyth Network Price Feeds page to browse all available feeds
Common price feed IDs:
- BTC/USD: e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43
- ETH/USD: ff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace
- SOL/USD: ef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d

Project Structure

pyth-network-mcp/
├── pyth_tools.py                # Pyth Network API client
├── pyth_mcp_server.py           # Official MCP server
├── pyth_mcp_client.py           # Example client
├── pyproject.toml               # Dependencies
├── README.md                    # This file
├── STRUCTURE.md                 # Structure guide
├── .gitignore
└── fastmcp-implementation/      # Alternative FastMCP implementation

Architecture

This official MCP server uses:

Official MCP SDK: Standards-compliant MCP protocol implementation
stdio transport: For efficient communication with MCP clients
Pyth Hermes API: Pyth's REST API for accessing price feed data (https://hermes.pyth.network)
httpx: Async HTTP client for making API requests

The server operates statelessly, fetching fresh data from Pyth's Hermes API on each request. Binary data is disabled by default for clean, human-readable responses.

When to Use This vs FastMCP?

This repository contains two implementations of the Pyth Network MCP server:

Official MCP (This Root Directory) ✅ Recommended

When to use:

✅ Production deployments - Standards-compliant and battle-tested
✅ Claude Desktop integration - Official protocol support
✅ Cursor/Windsurf integration - Best compatibility with AI IDEs
✅ Better performance - Efficient stdio transport
✅ Future-proof - Follows MCP specification exactly
✅ Stable & reliable - Official SDK with proper error handling

Transport: stdio (standard input/output)
Protocol: Official MCP SDK
Best for: Production, AI agents, real applications

FastMCP Implementation (Subdirectory)

When to use:

🧪 Learning & experimentation - Simpler to understand
🧪 HTTP/SSE preferred - If you need HTTP-based transport
🧪 Quick prototyping - Fast to set up and test
🧪 Educational purposes - Great for learning MCP concepts

Transport: HTTP with Server-Sent Events (SSE)
Protocol: FastMCP framework
Best for: Learning, experimentation, HTTP-based workflows

Quick Comparison

Feature	Official MCP (Root)	FastMCP (Subfolder)
Production Ready	✅ Yes	🔶 Basic
Performance	✅ Excellent	🔶 Good
Claude Desktop	✅ Full support	✅ Supported
Transport	stdio	HTTP/SSE
Ease of Learning	🔶 Moderate	✅ Easy
Protocol Compliance	✅ Official spec	🔶 Framework-based
Recommended for	Production use	Learning/testing

📝 Note: Both implementations provide the same five tools and access to the same Pyth Network data. The difference is in the underlying transport and protocol implementation.

See for FastMCP documentation.

License

This project is licensed under the MIT License.

About

Pyth Network is a decentralized oracle protocol that delivers real-time market data to smart contracts across 107+ blockchains. By aggregating data from over 125 first-party publishers—including major exchanges, market makers, and trading firms—Pyth provides reliable and low-latency price feeds for various asset classes.

This MCP server makes Pyth's extensive price feed network easily accessible to AI agents, autonomous systems, and other applications through the Model Context Protocol, enabling intelligent agents to make informed decisions based on real-time market data.

External Resources

Pyth Network: https://pyth.network
Pyth Documentation: https://docs.pyth.network
Hermes API Docs: https://hermes.pyth.network/docs
Price Feeds: https://pyth.network/price-feeds
MCP Protocol: https://modelcontextprotocol.io
GitHub: https://github.com/itsomsarraf/pyth-network-mcp

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues related to:

This MCP Server: Open an issue on GitHub
Pyth Network: Visit Pyth's Discord or documentation
MCP Protocol: See Model Context Protocol documentation

itsOmSarraf/pyth-network-mcp

Pyth Network MCP Server

Table of Contents

Features

🔧 Tools (5 Available)

💬 Prompts (4 Available)

📚 Resources (3 Available)

🌐 Universal Features

Supported Asset Types and Coverage

Prerequisites

Installation

Clone the Repository

Install Dependencies

Configure MCP Client

Running the Server

Usage

MCP Capabilities Overview

Tool: get_price_feeds

Tool: get_latest_price_updates

Tool: get_price_updates_at_time

Tool: get_publisher_stake_caps

Tool: get_twap_latest

Prompts

Prompt: analyze_price_feed

Prompt: compare_prices

Prompt: market_overview

Prompt: price_alert_setup

Resources

Resource: pyth://network/info

Resource: pyth://feeds/popular

Resource: pyth://docs/api

Testing the Server

Finding Price Feed IDs

Project Structure

Architecture

When to Use This vs FastMCP?

Official MCP (This Root Directory) ✅ Recommended

FastMCP Implementation (Subdirectory)

Quick Comparison

License

About

External Resources

Contributing

Support

Tool: `get_price_feeds`

Tool: `get_latest_price_updates`

Tool: `get_price_updates_at_time`

Tool: `get_publisher_stake_caps`

Tool: `get_twap_latest`

Prompt: `analyze_price_feed`

Prompt: `compare_prices`

Prompt: `market_overview`

Prompt: `price_alert_setup`

Resource: `pyth://network/info`

Resource: `pyth://feeds/popular`

Resource: `pyth://docs/api`