GridPulse MCP server
Commit Oct 26, 2026Provides pay-per-call U.S. energy market data including grid mix, retail electricity prices, and natural gas prices via the x402 protocol.
Also known as noah-silver/gridpulse, gridpulse
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.1
- Last commit
- Oct 26, 2026
- License
- —
What is GridPulse MCP?
GridPulse provides pay-per-call U.S. energy market data including grid mix, retail electricity prices, and natural gas prices via the x402 protocol.
Summary generated from the project's README
About GridPulse MCP server
GridPulse provides access to U.S. energy market data through a pay-per-call model designed for AI agents. It delivers information sourced from the U.S. Energy Information Administration, including hourly grid mix by fuel, retail electricity prices by state and sector, and Henry Hub natural gas spot prices. The server operates using the x402 protocol, allowing users to pay for specific data requests using USDC on either the Algorand or Base networks.
Developers can integrate this server into clients like Claude Desktop, Claude Code, or Cursor. Setup requires a wallet containing USDC to handle individual tool calls such as grid_mix or retail_electricity_price. Because there is no traditional signup or API key requirement for buyers, the system relies on direct blockchain payments for each request. The service also includes utility endpoints for checking the reliability of x402 sellers and monitoring Algorand network health.
What you can do with it
- 1Analyze regional energy generationRequest the latest hourly generation mix for a specific grid region to see renewable and carbon-free shares.
- 2Monitor electricity costsRetrieve retail electricity prices for a specific state and sector along with historical data.
- 3Track natural gas pricingGet the current Henry Hub natural gas spot price and related 30-day statistics.
- 4Verify seller reliabilityCheck the reliability score of an x402 seller based on uptime and settlement history.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ALGORAND_MNEMONICSecret25-word phrase of a small spending wallet with USDC on Algorand (optional)
EVM_PRIVATE_KEYSecretPrivate key of a small spending wallet with USDC on Base (optional)
| Name | Description | |
|---|---|---|
| ALGORAND_MNEMONIC | 25-word phrase of a small spending wallet with USDC on Algorand (optional) | Secret |
| EVM_PRIVATE_KEY | Private key of a small spending wallet with USDC on Base (optional) | Secret |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenoah-silver/gridpulse is public and reachablegithub.com/noah-silver/gridpulse ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-26github.com/noah-silver/gridpulse ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub⚡ GridPulse
Pay-per-call U.S. energy market data for AI agents. Agents pay per call in USDC on Algorand or Base using the x402 protocol. No signup and no API keys for buyers.
| Endpoint | Price | Returns |
|---|---|---|
GET /v1/grid-mix?region=ERCO |
$0.02 | Latest hourly generation mix for a grid region (MWh by fuel, renewable and carbon-free share) |
GET /v1/retail-price?state=CT§or=RES |
$0.01 | Retail electricity price by state and sector, year-over-year change, 12-month history |
GET /v1/henry-hub |
$0.01 | Henry Hub natural gas spot price, 30-day stats and history |
GET /v1/seller-check?url=… |
$0.01 | x402 Seller Check: 0–100 reliability score for any x402 seller (uptime probes, settlement history, age, buyer diversity) |
GET /v1/sellers/search?q=weather&maxPrice=0.05 |
$0.02 | Find reliable x402 sellers for a task, ranked by Seller Check score |
GET /v1/algorand/network-health |
$0.008 | Algorand block time, TPS, online stake share, health (Algorand USDC only) |
GET /v1/algorand/account?address=… |
$0.01 | Spendable ALGO, can it pay fees, can it receive USDC, staking and rekey status (Algorand USDC only) |
GET /v1/algorand/asset?id=31566704 |
$0.015 | ASA supply, Pera verification tier, clawback/freeze risk flags (Algorand USDC only) |
GET /v1/algorand/tx?id=… |
$0.01 | Plain-English transaction explainer with decoded note (Algorand USDC only) |
GET /v1/crypto/market-pulse |
$0.015 | ALGO/BTC/ETH/SOL/USDC prices cross-checked on Coinbase + Kraken (Algorand USDC only) |
Live on Algorand MainNet: https://noahs-mac-mini.tail571e99.ts.net
Free: / (landing page), /llms.txt (docs for agents), /health.
Data source: U.S. Energy Information Administration (public domain).
Use it from your agent
Any x402 client works: call the endpoint, get 402 Payment Required, pay, retry. The @x402/fetch wrapper does all of this automatically.
- OpenAPI spec: https://noahs-mac-mini.tail571e99.ts.net/openapi.json
- Agent docs: https://noahs-mac-mini.tail571e99.ts.net/llms.txt
Pay with USDC on Base (npm i @x402/fetch @x402/evm viem):
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { toClientEvmSigner } from "@x402/evm";
import { createPublicClient, http } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const signer = toClientEvmSigner(account, createPublicClient({ chain: base, transport: http() }));
const client = new x402Client().register("eip155:8453", new ExactEvmScheme(signer));
const fetchWithPay = wrapFetchWithPayment(fetch, client);
const res = await fetchWithPay("https://noahs-mac-mini.tail571e99.ts.net/v1/grid-mix?region=CISO");
console.log(await res.json());
Pay with USDC on Algorand: see src/pay.ts (uses @x402/avm).
MCP server (Claude Desktop, Claude Code, Cursor, …)
One-click (Claude Desktop): download gridpulse-mcp.mcpb, open it, and optionally enter a small spending wallet. Also listed in the official MCP Registry as io.github.noah-silver/gridpulse.
Or configure it manually:
Add GridPulse as tools (grid_mix, retail_electricity_price, henry_hub_gas_price). Each tool call pays from your own wallet via x402. Use a small, dedicated spending wallet, never your main one.
{
"mcpServers": {
"gridpulse": {
"command": "npx",
"args": ["-y", "github:noah-silver/gridpulse"],
"env": { "EVM_PRIVATE_KEY": "0x… (Base wallet holding a little USDC)" }
}
}
}
Use ALGORAND_MNEMONIC instead of (or as well as) EVM_PRIVATE_KEY to pay with USDC on Algorand.
Setup guide (Mac mini)
Run each command in Terminal on the Mac mini, one at a time.
1. Install Node.js
brew install node
If brew isn't found, install Homebrew first from https://brew.sh.
2. Get the code and install
Copy this gridpulse folder onto the Mac mini (AirDrop works), then:
cd ~/gridpulse
npm install
cp .env.template .env
open -e .env
3. Fill in .env
- PAY_TO_ADDRESS: create a new account in Pera for receiving payments. Fund it with about 1 ALGO and opt it in to USDC (in Pera: Add Asset, then search USDC, asset ID 31566704). Paste its address here.
- EIA_API_KEY: free, instant, at https://www.eia.gov/opendata/register.php
- Leave
NETWORK=testnetfor now.
4. Run it
npm start
Open http://localhost:4021 to see the landing page. http://localhost:4021/v1/henry-hub should return 402 Payment Required, which means the paywall is working. Press Ctrl+C to stop.
5. Give it a public HTTPS address
Pick one:
Option A: Tailscale Funnel (free, easiest). You get a permanent URL like https://mac-mini.tail1234.ts.net.
brew install tailscale
Sign in, then run:
tailscale funnel --bg 4021
Option B: Cloudflare Tunnel with your own domain (about $10/yr, looks more professional). Buy a domain such as gridpulse.xyz in Cloudflare, then:
brew install cloudflared
cloudflared tunnel login
cloudflared tunnel create gridpulse
cloudflared tunnel route dns gridpulse api.YOURDOMAIN.com
cloudflared tunnel run --url http://localhost:4021 gridpulse
Put the resulting URL in .env as PUBLIC_URL.
6. Switch to MainNet and keep it running 24/7
In .env, set NETWORK=mainnet. Then:
npm install -g pm2
pm2 start npm --name gridpulse -- start
pm2 save
pm2 startup
(pm2 startup prints one more command to copy and run.) In System Settings → Energy, turn on "Prevent automatic sleeping" and "Start up automatically after a power failure."
7. Make the first real payment (required by the contest)
Create another new Pera account as the "buyer." Put about $1 of USDC and 0.3 ALGO in it. Add its 25-word phrase to .env as BUYER_MNEMONIC.
Never use the phrase of your main wallet.
npm run pay -- "/v1/grid-mix?region=ISNE"
npm run pay -- "/v1/retail-price?state=CT"
npm run pay -- /v1/henry-hub
Each settled payment lists that endpoint in the Bazaar and on the leaderboard.
8. Submit (by September 30)
- Push this folder to a public GitHub repo.
.envis git-ignored, so your secrets stay local. - Add the repo to Electric Capital open-dev-data.
- Fill in the submission form.
Technical notes
@x402/*packages are pinned to 2.17.0, and network IDs are hardcoded in the legacy format that the hosted GoPlausible facilitator currently expects (x402-foundation/x402#3528). Don't upgrade until the facilitator is updated.- The facilitator pays Algorand network fees. Buyers need only USDC.
- EIA responses are cached for 10 minutes.
- Invalid inputs return 400 and upstream failures return 502. Neither response is settled, so buyers aren't charged.
GridPulse MCP questions
How do I pay for the data?
Agents pay per call using USDC on Algorand or Base via the x402 protocol.
Do I need to sign up or use API keys to buy data?
No, there is no signup or API key required for buyers.
Are there any costs for invalid requests?
No, invalid inputs or upstream failures do not result in settled payments, so buyers are not charged.