mineryield-mcp

MinerYield is for home miners and small businesses with solar and battery in the numbers. This MCP server (and the hosted endpoint at https://mineryield.com/mcp) exposes the same leftover-watt solar / battery / grid model the site calculator already uses. Tools call https://mineryield.com/api/v1/**. They do not reimplement profitability math.

Ask an assistant:

• "I have a 10 kW solar array and a 20 kWh battery, which miner makes the most per day?"
• "a 3 kW miner on solar by day, grid at $0.15/kWh at night"

list_miners answers the first (optional solarW=10000, batteryCapacity=20, sort PROFIT/DAY). calculate_profitability answers the second (power=3000, elecCost=0.15, powerSources={solar:true, battery:false, grid:true}).

Figures are model estimates from live market and weather inputs. They are estimates only, not investment, financial, or tax advice, not ROI guarantees, and not hardware telemetry. Results vary with network difficulty, coin price, power cost, and hardware performance. Do your own research.

Admin routes (/api/v1/admin/*) are not exposed.

Requirements: Node.js 22 or newer.

Hosted endpoint: https://mineryield.com/mcp (Streamable HTTP, Authorization: Bearer <key>). Setup page: mineryield.com/ai/.

Registry name: io.github.nadeaup/mineryield-mcp

What's supported (existing site calculator)

No new calculation logic. These are the site calculator inputs the tools already forward:

Input	Units	Meaning
solarW	Watts (10000 = 10 kW)	Array capacity. Solar generation is treated as free during the Peak Sun Hours window.
batteryCapacity	kWh (20 = 20 kWh)	Storage. Excess daytime solar charges it; it covers night hours before grid.
zipCode	5-digit US ZIP	Peak Sun Hours. Defaults to the API-key owner profile, then a server default.
elecCost	USD / kWh (0.15 = 15 cents)	One leftover-grid rate. There is no separate day/night tariff: solar covers the sun window, leftover night kWh use this price when grid is on.
powerSources	{ solar, battery, grid }	Which legs to use. solar + grid + battery:false is "solar by day, grid at night". grid:false means the miner only runs while solar or battery energy lasts (runtimeHours < 24).

On GET /api/v1/miners / list_miners, query values override the API-key owner profile. Sending solarW without solar=false turns solar on; sending batteryCapacity without battery=false turns battery on.

get_solar_forecast is weather-based array production only (zipCode + capacityW). Pair it with list_miners or calculate_profitability for miner profit.

API key

Create a Bearer API key while signed in at mineryield.com/api with a verified email (create/list/revoke/rotate use a Firebase ID token; email_not_verified → 403). Set it as MINERYIELD_API_KEY. Never commit it.

Optional: MINERYIELD_API_BASE_URL (defaults to https://mineryield.com).

Setup walkthrough: Use MinerYield in your AI assistant.

npx (recommended)

export MINERYIELD_API_KEY="your-key"
npx -y mineryield-mcp

Local Streamable HTTP (for debugging a hosted-style client):

npx -y mineryield-mcp --http --port 3333

npm package

npm install -g mineryield-mcp
export MINERYIELD_API_KEY="your-key"
mineryield-mcp

From this repository:

npm install
npm run build
export MINERYIELD_API_KEY="your-key"
npm start

Claude Desktop

Add to claude_desktop_config.json (Claude → Settings → Developer):

{
  "mcpServers": {
    "mineryield": {
      "command": "npx",
      "args": ["-y", "mineryield-mcp"],
      "env": {
        "MINERYIELD_API_KEY": "your-key"
      }
    }
  }
}

Or connect Claude to the hosted endpoint https://mineryield.com/mcp with Authorization: Bearer your-key.

Cursor

This repository also ships .cursor-plugin/plugin.json and a root mcp.json (runs npx -y mineryield-mcp).

Published package / npx snippet for Cursor MCP settings:

{
  "mcpServers": {
    "mineryield": {
      "command": "npx",
      "args": ["-y", "mineryield-mcp"],
      "env": {
        "MINERYIELD_API_KEY": "your-key"
      }
    }
  }
}

Hosted Streamable HTTP:

{
  "mcpServers": {
    "mineryield": {
      "url": "https://mineryield.com/mcp",
      "headers": {
        "Authorization": "Bearer your-key"
      }
    }
  }
}

ChatGPT and other MCP clients

Use Streamable HTTP:

• URL: https://mineryield.com/mcp
• Auth: Authorization: Bearer <MINERYIELD_API_KEY>
• Discovery: https://mineryield.com/.well-known/mcp.json

ChatGPT (Connectors / custom MCP), Claude remote MCP, and Grok custom connectors all accept that URL plus the Bearer header. Private tools require a Bearer key. A small keyless catalog subset (list_catalog_miners, list_mrr_rates, list_nicehash_rates, get_market_data plus initialize/tools/list/ping) shares 20/UTC minute and 200/UTC day (Firestore, not per IP). Quota denial never falls back to anonymous.

OpenAPI remains the HTTP contract: mineryield.com/swagger.yaml.

Limits and errors

• Keyless hosted MCP: 20 requests / UTC minute and 200 / UTC day shared (Firestore). Tools: list_catalog_miners, list_mrr_rates, list_nicehash_rates, get_market_data (+ initialize / tools/list / ping).
• Free plan: 25 REST API calls / rolling 30 days (keyed MCP tools consume the same quota).
• Paid: 1,000 / 10,000 / 50,000 (Hobbyist / Pro / Expert). Hosted MCP also rate-limits 60/min per key and 30/min per address (per instance). Max 5 active keys.
• x402: not enabled.
• Errors: missing/invalid Bearer → 401; key create without verified email → 403 email_not_verified; over quota → 429 {"error":"Quota Exceeded","code":"quota_exceeded","remaining","limit","resetAt","retryAfterSeconds","period"} with Retry-After / RateLimit-* headers.

Tools

Tool	HTTP	Auth	Purpose
list_miners	GET /api/v1/miners	Bearer API key	Rank catalog ASICs by daily profit for a home/small-business solar+battery+grid setup. Optional solarW, batteryCapacity, zipCode, elecCost, powerSources override the key-owner profile. Same SKUs as the UI, including KDA/NEXA/XP/ALEO/ALPH.
get_rigs	GET /api/v1/rigs	Bearer API key	Saved My Rigs plus per-unit estimates (includes NiceHash daily revenue when a rate exists)
calculate_profitability	POST /api/v1/calculator	Bearer API key	One-machine leftover-watt model (algorithm catalog names include Kadena, NexaPow, XPHash; SHA-256 preferredCoin may be QUAI)
get_market	GET /api/v1/market	Bearer API key	Live spot prices (BTC, BCH, LTC, DOGE, ZEC, KAS, CKB, RXD, SC, DCR, DASH, GRIN, ALPH, XTM, ETC, XMR, ALEO, HNS, BTCB2, KDA, NEXA, XP, QUAI, ARRR, OCTA, ETHW, QKC, MWC, SCP)
get_solar_forecast	GET /api/v1/solar-forecast	Bearer API key	7-day solar production estimate (zipCode, capacityW)
get_difficulty_prediction	GET /api/v1/difficulty-prediction	Bearer API key	7-day difficulty trend (coin, default BTC; allowlist is the supported market symbol set)
list_catalog_miners	GET /api/v1/catalog/miners	Public	Specs-only ASIC catalog (Kadena, NexaPow, XPHash, ALEO, ALPH, SHA-256 QUAI-capable SKUs). Goldshell HS-Lite is one row with dual modes (Blake2B-SHA3/HNS and Blake2B SC/BTCB2).
list_mrr_rates	GET /api/v1/mrr-rates	Public	Cached Mining Rig Rentals algorithm rates. NexaPow maps to nexapow. SHA3X, zkSNARK, Blake256R14, Kadena, and XPHash have no primary book.
list_nicehash_rates	GET /api/v1/nicehash-rates	Public	Cached NiceHash paying rates (sat/H/day). SHA3X, zkSNARK, Blake256R14, Kadena, and XPHash have no NiceHash book.
get_market_data	GET /api/v1/market-data	Public	Full market payload used by the web app (includes KDA/NEXA/XP/QUAI/ARRR/OCTA/ETHW/QKC/MWC/SCP prices + nethash/difficulty; new-coin and XP fields may be omitted)

calculate_profitability body

Matches POST /api/v1/calculator in the OpenAPI spec:

Field	Required	Notes
hashrate	yes	Catalog units (TH/s for SHA-256 and Kadena, GH/s for NexaPow and XPHash, MH/s for Scrypt)
power	yes	Watts (3000 = 3 kW)
algorithm	yes	Catalog name (SHA-256, Scrypt, Kadena, NexaPow, XPHash, KHeavyHash, …)
elecCost	yes	USD / kWh leftover-grid rate
solarW	no	Array watts
zipCode	no	5-digit US ZIP for Peak Sun Hours
hardwareCost	no	USD, used for estimated payback days
batteryCapacity	no	kWh
powerSources	no	{ solar, battery, grid } booleans
preferredCoin	no	e.g. BTC/BCH/QUAI, SC/BTCB2, BTCB2/SC, ZEC/ARRR, ETC/OCTA/ETHW/QKC, DCR/SCP. Blake2B-SHA3 is HNS only; Cuckatoo31 is MWC only; Cuckatoo32 is GRIN only. Scrypt reports LTC/DOGE (merged). When omitted, the most profitable supported coin is used except Ethash4G, which defaults to ETC.

API-key management (not a tool)

GET / POST / DELETE /api/v1/api-keys require a Firebase ID token from a signed-in browser session, not the Bearer API key. Creating or revoking keys from an agent is not part of this default tool set. Use the site at /api.

Example prompts

• "I have a 10 kW solar array and a 20 kWh battery, which miner makes the most per day?"
• "a 3 kW miner on solar by day, grid at $0.15/kWh at night"
• "List MinerYield catalog ASICs and show name, algorithm, hashrate, and watts."
• "Estimate daily profit for a 200 TH/s, 3500 W SHA-256 miner at $0.12/kWh with 10 kW solar in ZIP 10001. This is a model estimate, not a guarantee."
• "Estimate daily profit for a Bitmain KA3 (166 TH/s Kadena) at $0.12/kWh."
• "Calculate SHA-256 profitability for 200 TH/s with preferredCoin QUAI."
• "What are the current MinerYield spot prices for BCH, KAS, ETC, XMR, and QUAI?"
• "Get a 7-day difficulty prediction for KDA."
• "Get a 7-day solar forecast for ZIP 85001 with a 8 kW array."
• "Show my saved MinerYield rigs and their estimated daily profit."

Tests

npm install
npm test

Releasing

Publish npm first, then the official MCP Registry.

1. Bump the same version in package.json and server.json (including packages[0].version). mcpName / name stay io.github.nadeaup/mineryield-mcp.
2. npm publish from a trusted machine (runs npm run build via prepublishOnly).
3. Push a v* tag, create a GitHub Release, or run Actions → Publish to MCP Registry on main. That workflow uses GitHub OIDC (mcp-publisher login github-oidc); it does not need a personal GitHub token and does not republish npm.

If the Registry already has that version, the workflow treats it as success. See RELEASING.md.

Hosted Streamable HTTP

Production endpoint: https://mineryield.com/mcp

Bearer API-key auth uses the same key store as /api/v1 for private tools. Admin routes and tools are not mounted. Keyless catalog subset uses the shared 20/min + 200/day anonymous budget. Per-key and per-address rate limits apply for authenticated traffic; keyed tool calls consume the rolling REST quota (25 free / paid tiers above).

Discovery:

• https://mineryield.com/llms.txt
• https://mineryield.com/.well-known/mcp.json (same document as /mcp-discovery.json)
• https://mineryield.com/ai/

License

MIT