Blocknative Gas Oracle Service

An MCP microservice leveraging Blocknative's infrastructure to supply live estimations for network transaction costs across multiple blockchains.

Core Capabilities

• Functions:
• fetch_fee_projections: Retrieves anticipated transaction fees for a designated network (default: Ethereum Mainnet, chain_id=1), detailing the baseline cost alongside a granular breakdown by assurance level, including associated price, priority surcharge, and maximum charge.
• calculate_tx_expenditure: Models the total transaction expenditure based on the stipulated gas limit, required confidence threshold, and network identifier, reporting results in both Gwei and Ether denominations.
• enumerate_supported_networks: Provides a comprehensive list of supported distributed ledgers, presented in a structured table showing network ID, underlying system, and connection type.
• Interaction Pattern:
• fee_inquiry_template: A structured communication template for soliciting fee quotations at a specified confidence rating and network identifier.
• Asynchronous Operation: Employs httpx for efficient, non-blocking retrieval of data from Blocknative's Fee Prediction and Network Catalog APIs.
• API Key Requirement: Tolerates minimal interaction without a Blocknative credential; sustained, high-volume querying necessitates setting the BLOCKNATIVE_API_KEY environment variable.

Prerequisites for Deployment

• Runtime Environment: Python version 3.10 or newer.
• Dependency Manager: uv for setting up the environment and initiating the service (Installation Guide).
• Blocknative Credential (Optional): Mandatory for high-throughput access. Obtain credentials from Blocknative.

Setup Procedure

1. Source Code Acquisition: bash git clone https://github.com/kukapay/blocknative-mcp.git cd blocknative-mcp

2. Environment Initialization with uv: bash uv sync

3. Configuring the Blocknative Key (Optional):

4. For intensive usage, define the environment variable: bash export BLOCKNATIVE_API_KEY="your-api-key-here"

5. This step can be omitted for low-frequency operations.

Operational Guidelines

The service exposes three distinct functions and one pre-defined communication template via the FastMCP orchestration layer. Users can initiate the service in a debugging state, execute it directly, or integrate it into Claude Desktop workflows.

Launching the Service

1. Development Mode with MCP Inspector: bash uv run mcp dev blocknative-mcp

This action launches a web-based Inspector UI for interactive function testing.

1. Direct Execution: bash uv run blocknative-mcp

2. Integration with Claude Desktop: bash uv run mcp install blocknative-mcp --name "Blocknative Gas Oracle Service"

This command registers the service for use within the Claude Desktop environment.

Available Functions

• fetch_fee_projections(chain_id: int = 1) -> str: Obtains cost forecasts for a specified network (default: Ethereum Mainnet). Output includes the base tariff and a formatted Markdown tabulation detailing assurance levels, quoted price, priority surcharge, and aggregate maximum fee.

• Example Output: markdown Gas Price Projections for Chain ID 1 (ethereum/main):

  • Base Fee Per Gas: 0.382910791 Gwei

  Confidence	Price (Gwei)	Max Priority Fee (Gwei)	Max Fee (Gwei)
  99%	0.52	0.14	0.9
  95%	0.48	0.094	0.86
  90%	0.47	0.089	0.85
  80%	0.46	0.079	0.84
  70%	0.45	0.069	0.83

• calculate_tx_expenditure(gas_limit: int, confidence: int = 99, chain_id: int = 1) -> str: Calculates the anticipated expenditure for a transaction given the gas ceiling, certainty level, and network ID. Returns the totals denominated in Gwei and ETH.

• Example Output: markdown Estimated Gas Cost (Confidence 90%, Chain ID 1):

  • Gas Limit: 21000
  • Max Fee Per Gas: 0.85 Gwei
  • Total Cost: 17850 Gwei (0.00001785 ETH)

• enumerate_supported_networks(ctx: Optional[Context] = None) -> str: Lists the recognized distributed ledger technologies in a Markdown table, including their numerical ID, system identifier, and connection endpoint.

• Example Output: markdown Supported Networks:

  Chain ID	System	Network
  1	ethereum	main
  137	polygon	mainnet
  8453	base	mainnet
  11155111	ethereum	sepolia

Predefined Communication Templates

• fee_inquiry_template(confidence: int, chain_id: int = 1) -> List[base.Message]: A template for structuring requests to ascertain transaction costs for a specific confidence level and network identifier.
• Example Dialogue Flow: markdown
  • User: What is the current gas price for chain ID 1 transactions with 90% confidence?
  • Assistant: Let me fetch the gas price predictions for chain ID 1.

Licensing Information

This software is distributed under the terms of the MIT License. Review the LICENSE file for specifics.