# Pyth Network MCP Server (FastMCP)
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.
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
> **Note**: This is the FastMCP implementation (alternative). For the official MCP protocol implementation (recommended for production), see the root directory.
## Table of Contents
- [Features](#features)
- [Supported Asset Types and Coverage](#supported-asset-types-and-coverage)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Running the Server](#running-the-server)
- [Usage](#usage)
- [get_price_feeds](#tool-get_price_feeds)
- [get_latest_price_updates](#tool-get_latest_price_updates)
- [get_price_updates_at_time](#tool-get_price_updates_at_time)
- [get_publisher_stake_caps](#tool-get_publisher_stake_caps)
- [get_twap_latest](#tool-get_twap_latest)
- [Finding Price Feed IDs](#finding-price-feed-ids)
- [Architecture](#architecture)
- [Why FastMCP?](#why-fastmcp)
- [When to Use Official MCP?](#when-to-use-official-mcp)
- [Resources](#resources)
- [Contributing](#contributing)
- [Support](#support)
## Features
- **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
- **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
- **Universal Price Feed IDs**: Unlike chain-specific oracles, Pyth uses universal price feed IDs that work across all supported blockchains
- **Clean Data Output**: Binary proof data is OFF by default - get readable data instantly
## 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](https://docs.astral.sh/uv/) (recommended)
- **Claude Desktop** (optional): For integration with Anthropic's Claude interface
## Installation
### Clone the Repository
```bash
git clone https://github.com/itsomsarraf/pyth-network-mcp.git
cd pyth-network-mcp/fastmcp-implementation
```
### Install Dependencies
**Using uv (recommended):**
```bash
uv pip install -e .
```
**Using pip:**
```bash
pip install -e .
```
The project requires:
- `fastmcp>=2.12.4` - For MCP server functionality
- `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):
```json
{
"mcpServers": {
"pyth-network-fastmcp": {
"command": "python3",
"args": ["/absolute/path/to/pyth-network-mcp/fastmcp-implementation/pyth_mcp_server.py"]
}
}
}
```
**Using uv:**
```json
{
"mcpServers": {
"pyth-network-fastmcp": {
"command": "uv",
"args": ["run", "/absolute/path/to/pyth-network-mcp/fastmcp-implementation/pyth_mcp_server.py"]
}
}
}
```
## Running the Server
Start the MCP server with SSE transport:
```bash
python3 pyth_mcp_server.py
```
The server will start on `http://localhost:8000` with SSE transport enabled for HTTP access.
To test the server with the included client example:
```bash
python3 pyth_mcp_client.py
```
## Usage
The server exposes five tools via the MCP protocol, accessible through Claude Desktop (for natural language queries) or programmatically. Below are detailed descriptions of each tool 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."
---
### Tool: `get_latest_price_updates`
**Description**: Fetch the latest price updates for specific price feed IDs. Returns clean, parsed data by default (binary proof data available if needed).
**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 proof data. Default: `false`
**Returns**: Price updates with parsed data (and optionally binary data for smart contracts).
**Natural Language Example (Claude Desktop)**:
> **User**: "What's the current price of Bitcoin in USD?"
>
> **Assistant**: "The current BTC/USD price is $67,234.50 (as of 2 seconds ago). The price has a confidence interval of ±$12.30."
**Note**: The `price` value must be multiplied by `10^expo` to get the actual price. Example: `6723450000000 × 10^-8 = $67,234.50`
---
### 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 proof 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 12:00 PM UTC today?"
>
> **Assistant**: "At 12:00 PM UTC (timestamp 1704715200), the BTC/USD price was $66,890.25 with a confidence interval of ±$11.50."
---
### 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 proof data. Default: `false`
**Returns**: Latest publisher stake caps update data with parsed format (and optionally binary).
**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 data was updated 5 minutes ago and includes caps for all 125+ data providers."
---
### 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 proof 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 $67,180.35, which is slightly lower than the current spot price of $67,234.50. This indicates recent upward price movement."
---
## Testing the Server
The repository includes a demonstration client (`pyth_mcp_client.py`) that shows how to use all five tools. To test the server:
```bash
python3 pyth_mcp_client.py
```
## Finding Price Feed IDs
To find the correct price feed ID for your desired asset:
1. Use the `get_price_feeds` tool to search by symbol:
```
"Search for Ethereum price feeds"
```
2. Or visit the [Pyth Network Price Feeds page](https://pyth.network/price-feeds) to browse all available feeds
3. Common price feed IDs:
- BTC/USD: `e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43`
- ETH/USD: `ff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace`
- SOL/USD: `ef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d`
## Architecture
This FastMCP server uses:
- **FastMCP**: A Python framework for building MCP servers with HTTP/SSE transport
- **Pyth Hermes API**: Pyth's REST API for accessing price feed data (`https://hermes.pyth.network`)
- **httpx**: HTTP client for making API requests
The server operates statelessly, fetching fresh data from Pyth's Hermes API on each request.
## Why FastMCP?
- ✅ **Simple Setup**: Easy to understand and configure
- ✅ **HTTP-Based**: Familiar request/response model
- ✅ **Quick Prototyping**: Perfect for testing and development
- ✅ **Educational**: Great for learning MCP concepts
## When to Use Official MCP?
For production deployments and better performance, use the official MCP implementation in the root directory (`../`):
- ✅ Standards-compliant (official MCP protocol)
- ✅ Better performance (stdio transport)
- ✅ Full Claude Desktop integration
- ✅ Production-ready
- [View Official MCP README →](../README.md)
## 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.
## Resources
- **Pyth Network**: [https://pyth.network](https://pyth.network)
- **Pyth Documentation**: [https://docs.pyth.network](https://docs.pyth.network)
- **Hermes API Docs**: [https://hermes.pyth.network/docs](https://hermes.pyth.network/docs)
- **Price Feeds**: [https://pyth.network/price-feeds](https://pyth.network/price-feeds)
- **FastMCP**: [https://github.com/jlowin/fastmcp](https://github.com/jlowin/fastmcp)
- **GitHub Repository**: [https://github.com/itsomsarraf/pyth-network-mcp](https://github.com/itsomsarraf/pyth-network-mcp)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request to [https://github.com/itsomsarraf/pyth-network-mcp](https://github.com/itsomsarraf/pyth-network-mcp).
## Support
For issues related to:
- **This MCP Server**: Open an issue on [GitHub](https://github.com/itsomsarraf/pyth-network-mcp/issues)
- **Pyth Network**: Visit [Pyth's Discord](https://discord.gg/pythnetwork) or [documentation](https://docs.pyth.network)
- **FastMCP**: See [FastMCP documentation](https://github.com/jlowin/fastmcp)
- **MCP Protocol**: See [Model Context Protocol documentation](https://modelcontextprotocol.io)
---
**Looking for the official MCP implementation?** Check out the root directory (`../`) for the production-ready version.