mineryield-mcp
# 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/](https://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](https://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](https://mineryield.com/ai/).
## npx (recommended)
```bash
export MINERYIELD_API_KEY="your-key"
npx -y mineryield-mcp
```
Local Streamable HTTP (for debugging a hosted-style client):
```bash
npx -y mineryield-mcp --http --port 3333
```
## npm package
```bash
npm install -g mineryield-mcp
export MINERYIELD_API_KEY="your-key"
mineryield-mcp
```
From this repository:
```bash
npm install
npm run build
export MINERYIELD_API_KEY="your-key"
npm start
```
## Claude Desktop
Add to `claude_desktop_config.json` (Claude → Settings → Developer):
```json
{
"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:
```json
{
"mcpServers": {
"mineryield": {
"command": "npx",
"args": ["-y", "mineryield-mcp"],
"env": {
"MINERYIELD_API_KEY": "your-key"
}
}
}
}
```
Hosted Streamable HTTP:
```json
{
"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](https://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](https://mineryield.com/swagger.yaml):
| 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
```bash
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](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](LICENSE)
TDQS
Scored across 10 tools
Most tools have clearly distinct purposes, but there are two notable overlapping pairs: get_market vs get_market_data and list_miners vs list_catalog_miners. The descriptions do clarify the distinctions, such as public catalog specs versus profitability ranking, so confusion is limited but still possible.
All tool names use a consistent snake_case verb_noun pattern: list_miners, get_rigs, calculate_profitability, get_market, and so on. The naming is predictable and easy to scan.
Ten tools is well within the ideal 3-15 range for this server. Each tool covers a distinct part of the mining profitability workflow, and the set does not feel bloated or thin.
The server covers profitability calculation, miner catalogs, saved rigs, market prices, solar forecasts, difficulty predictions, and rental/rate snapshots. The main gap is that My Rigs appears read-only here, with no create/update/delete rig operations, though agents can still work around this via calculate_profitability.