@startminingmcp/mcp 1.1.0

package/README.md

@@ -0,0 +1,101 @@
+# @startminingmcp/mcp
+
+MCP (Model Context Protocol) server for Bitcoin mining data. Get real-time hashprice, difficulty, profitability calculations, and more.
+
+## 🚀 Features
+
+- **Real-time market data** — BTC price, hashprice, difficulty, network stats
+- **Profitability calculator** — Calculate ROI for any ASIC setup
+- **Historical data** — Price and difficulty history since 2009
+- **Halving tracker** — Current era, next halving, supply stats
+- **Mempool & blocks** — Fee estimates and recent blocks
+- **ASIC prices** — Market prices by efficiency tier
+
+## 📦 Installation
+
+```bash
+npm install -g @startminingmcp/mcp
+```
+
+Or use directly with npx:
+
+```bash
+npx @startminingmcp/mcp
+```
+
+## ⚙️ Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "startmining": {
+      "command": "npx",
+      "args": ["@startminingmcp/mcp"]
+    }
+  }
+}
+```
+
+### With API Key (optional, for higher rate limits)
+
+```json
+{
+  "mcpServers": {
+    "startmining": {
+      "command": "npx",
+      "args": ["@startminingmcp/mcp"],
+      "env": {
+        "STARTMINING_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+## 🛠️ Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_market_data` | Current BTC price, hashprice, difficulty, network stats |
+| `get_hashprice` | Hashprice breakdown ($/PH/day) |
+| `get_difficulty` | Current difficulty + next adjustment prediction |
+| `get_halving_info` | Halving era, next date, supply stats |
+| `get_price_history` | Historical BTC prices (from, to, granularity) |
+| `get_difficulty_history` | Historical difficulty & hashrate |
+| `get_monthly_averages` | Calendar-month averages (UTC) of BTC price, hashrate, hashprice USD & BTC (month: YYYY-MM) |
+| `calculate_profitability` | Mining profitability for given setup |
+| `calculate_breakeven` | Breakeven BTC price |
+| `get_mempool` | Mempool status & fee estimates |
+| `get_recent_blocks` | Recent blocks info |
+| `get_asic_prices` | ASIC market prices by efficiency |
+
+## 💡 Example Queries
+
+Once configured, you can ask Claude:
+
+- "What's the current hashprice?"
+- "Calculate profitability for an S21 (200 TH/s, 3500W) at $0.05/kWh"
+- "When is the next halving?"
+- "Show me BTC price history for last month"
+- "What's the mempool fee situation?"
+- "Give me the September 2026 monthly averages for price, hashrate and hashprice"
+
+## 📊 Data Sources
+
+- **Price data**: Internal database (since 2009-01-03)
+- **Network data**: Direct Bitcoin Core node
+- **Calculations**: Real-time based on current conditions
+
+## 🔗 Links
+
+- **Website**: [pro.startmining.io](https://pro.startmining.io)
+- **Company**: [startmining.io](https://startmining.io)
+- **API Docs**: [mining-api.startmining.io](https://mining-api.startmining.io)
+
+## 📄 License
+
+MIT © [Startmining](https://startmining.io)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { computeMonthlyAverages, monthRange } from "./monthly.js";
+const API_BASE = process.env.STARTMINING_API_URL || "https://mining-api.startmining.io";
+// Default public API key for MCP (rate limited, read-only)
+const DEFAULT_PUBLIC_KEY = "sm_mcp_public_2026_xKj8mNpL4qRsT9wV2yHz";
+const API_KEY = process.env.STARTMINING_API_KEY || DEFAULT_PUBLIC_KEY;
+const MCP_VERSION = "1.1.0";
+// Analytics tracking (fire-and-forget, non-blocking)
+function trackToolCall(toolName) {
+    const payload = {
+        tool: toolName,
+        version: MCP_VERSION,
+        ts: Date.now(),
+    };
+    fetch(`${API_BASE}/v1/mcp/track`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+    }).catch(() => { }); // Silent fail, never blocks
+}
+async function fetchAPI(endpoint) {
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (API_KEY) {
+        headers["X-API-Key"] = API_KEY;
+    }
+    const response = await fetch(`${API_BASE}${endpoint}`, { headers });
+    if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+}
+async function postAPI(endpoint, body) {
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (API_KEY) {
+        headers["X-API-Key"] = API_KEY;
+    }
+    const response = await fetch(`${API_BASE}${endpoint}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+}
+// Create MCP server
+const server = new Server({
+    name: "startmining-mcp",
+    version: MCP_VERSION,
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Define available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "get_market_data",
+            description: "Get current Bitcoin market and mining data including price, hashprice, difficulty, and network stats",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "get_hashprice",
+            description: "Get current hashprice (mining revenue per PH/day) with detailed breakdown",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "get_difficulty",
+            description: "Get current difficulty and next adjustment prediction",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "get_halving_info",
+            description: "Get Bitcoin halving information - current era, next halving date, supply stats",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "get_price_history",
+            description: "Get historical Bitcoin prices",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    from: {
+                        type: "string",
+                        description: "Start date (YYYY-MM-DD)",
+                    },
+                    to: {
+                        type: "string",
+                        description: "End date (YYYY-MM-DD)",
+                    },
+                    granularity: {
+                        type: "string",
+                        enum: ["day", "hour"],
+                        description: "Data granularity (default: day). For calendar-month averages use get_monthly_averages",
+                    },
+                },
+                required: [],
+            },
+        },
+        {
+            name: "get_difficulty_history",
+            description: "Get historical difficulty and hashrate data",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    from: {
+                        type: "string",
+                        description: "Start date (YYYY-MM-DD)",
+                    },
+                    to: {
+                        type: "string",
+                        description: "End date (YYYY-MM-DD)",
+                    },
+                },
+                required: [],
+            },
+        },
+        {
+            name: "calculate_profitability",
+            description: "Calculate mining profitability for given hashrate and electricity cost",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    hashrate_th: {
+                        type: "number",
+                        description: "Hashrate in TH/s",
+                    },
+                    power_watts: {
+                        type: "number",
+                        description: "Power consumption in watts",
+                    },
+                    electricity_cost: {
+                        type: "number",
+                        description: "Electricity cost in $/kWh",
+                    },
+                    btc_price: {
+                        type: "number",
+                        description: "BTC price (optional, uses current if not provided)",
+                    },
+                    pool_fee_pct: {
+                        type: "number",
+                        description: "Pool fee percentage (default: 2)",
+                    },
+                    days: {
+                        type: "number",
+                        description: "Number of days to calculate (default: 30)",
+                    },
+                },
+                required: ["hashrate_th", "power_watts", "electricity_cost"],
+            },
+        },
+        {
+            name: "calculate_breakeven",
+            description: "Calculate breakeven BTC price for mining operation",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    hashrate_th: {
+                        type: "number",
+                        description: "Hashrate in TH/s",
+                    },
+                    power_watts: {
+                        type: "number",
+                        description: "Power consumption in watts",
+                    },
+                    electricity_cost: {
+                        type: "number",
+                        description: "Electricity cost in $/kWh",
+                    },
+                },
+                required: ["hashrate_th", "power_watts", "electricity_cost"],
+            },
+        },
+        {
+            name: "get_mempool",
+            description: "Get mempool status and fee estimates",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "get_recent_blocks",
+            description: "Get recent Bitcoin blocks",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    limit: {
+                        type: "number",
+                        description: "Number of blocks to return (default: 10)",
+                    },
+                },
+                required: [],
+            },
+        },
+        {
+            name: "get_monthly_averages",
+            description: "Get calendar-month averages (UTC) of BTC price, network hashrate, and hashprice in USD and BTC, for monthly mining reports. The month must be complete.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    month: {
+                        type: "string",
+                        description: "Calendar month (YYYY-MM), e.g. 2026-09 for 1-30 September 2026",
+                    },
+                },
+                required: ["month"],
+            },
+        },
+        {
+            name: "get_asic_prices",
+            description: "Get ASIC miner price data and efficiency stats",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+    ],
+}));
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    // Track usage (non-blocking)
+    trackToolCall(name);
+    try {
+        switch (name) {
+            case "get_market_data": {
+                const data = await fetchAPI("/market/current");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(data, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "get_hashprice": {
+                const data = await fetchAPI("/calculator/hashprice");
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            case "get_difficulty": {
+                const data = await fetchAPI("/market/difficulty");
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            case "get_halving_info": {
+                const data = await fetchAPI("/market/halving");
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            case "get_price_history": {
+                const params = new URLSearchParams();
+                if (args?.from)
+                    params.set("from", String(args.from));
+                if (args?.to)
+                    params.set("to", String(args.to));
+                if (args?.granularity)
+                    params.set("granularity", String(args.granularity));
+                const query = params.toString() ? `?${params}` : "";
+                const data = await fetchAPI(`/price/history${query}`);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            case "get_difficulty_history": {
+                const params = new URLSearchParams();
+                if (args?.from)
+                    params.set("from", String(args.from));
+                if (args?.to)
+                    params.set("to", String(args.to));
+                const query = params.toString() ? `?${params}` : "";
+                const data = await fetchAPI(`/difficulty/history${query}`);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            case "calculate_profitability": {
+                const data = await postAPI("/calculator/profitability", {
+                    hashrate_th: args?.hashrate_th,
+                    power_watts: args?.power_watts,
+                    electricity_cost: args?.electricity_cost,
+                    btc_price: args?.btc_price,
+                    pool_fee_pct: args?.pool_fee_pct ?? 2,
+                    days: args?.days ?? 30,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            case "calculate_breakeven": {
+                const params = new URLSearchParams({
+                    hashrate_th: String(args?.hashrate_th),
+                    power_watts: String(args?.power_watts),
+                    electricity_cost: String(args?.electricity_cost),
+                });
+                const data = await fetchAPI(`/calculator/breakeven?${params}`);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            case "get_mempool": {
+                const data = await fetchAPI("/network/mempool");
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            case "get_recent_blocks": {
+                const limit = args?.limit ?? 10;
+                const data = await fetchAPI(`/network/blocks?limit=${limit}`);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            case "get_monthly_averages": {
+                const month = String(args?.month ?? "");
+                const { from, to } = monthRange(month);
+                const data = await fetchAPI(`/calculator/hashprice/history?from=${from}&to=${to}`);
+                const averages = computeMonthlyAverages(month, data.history);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(averages, null, 2) }],
+                };
+            }
+            case "get_asic_prices": {
+                const data = await fetchAPI("/asic-prices/stats");
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Startmining MCP server running on stdio");
+}
+main().catch(console.error);

package/dist/monthly.d.ts

@@ -0,0 +1,30 @@
+export interface HashpriceHistoryPoint {
+    date: string;
+    hashprice_usd_ph_day: number;
+    btc_price_usd: number;
+    network_hashrate_eh: number;
+}
+export interface MonthlyAverages {
+    month: string;
+    from: string;
+    to: string;
+    days: number;
+    btc_price_usd: number;
+    network_hashrate_eh: number;
+    hashprice_usd_ph_day: number;
+    hashprice_usd_th_day: number;
+    hashprice_btc_ph_day: number;
+    hashprice_sats_th_day: number;
+    methodology: Record<string, string>;
+}
+/** First and last day (YYYY-MM-DD) of a calendar month given as YYYY-MM. */
+export declare function monthRange(month: string): {
+    from: string;
+    to: string;
+    days: number;
+};
+/**
+ * Calendar-month averages of the daily points. Refuses an incomplete month so a
+ * monthly report never silently relies on fewer days than the month contains.
+ */
+export declare function computeMonthlyAverages(month: string, history: HashpriceHistoryPoint[]): MonthlyAverages;

package/dist/monthly.js

@@ -0,0 +1,52 @@
+const round = (value, decimals) => Math.round(value * 10 ** decimals) / 10 ** decimals;
+const mean = (values) => values.reduce((sum, v) => sum + v, 0) / values.length;
+/** First and last day (YYYY-MM-DD) of a calendar month given as YYYY-MM. */
+export function monthRange(month) {
+    const match = /^(\d{4})-(0[1-9]|1[0-2])$/.exec(month);
+    if (!match) {
+        throw new Error("Invalid month. Use YYYY-MM (e.g. 2026-09)");
+    }
+    const year = Number(match[1]);
+    const monthIndex = Number(match[2]);
+    const days = new Date(Date.UTC(year, monthIndex, 0)).getUTCDate();
+    return {
+        from: `${month}-01`,
+        to: `${month}-${String(days).padStart(2, "0")}`,
+        days,
+    };
+}
+/**
+ * Calendar-month averages of the daily points. Refuses an incomplete month so a
+ * monthly report never silently relies on fewer days than the month contains.
+ */
+export function computeMonthlyAverages(month, history) {
+    const { from, to, days } = monthRange(month);
+    const points = history.filter((p) => p.date >= from && p.date <= to);
+    const uniqueDays = new Set(points.map((p) => p.date)).size;
+    if (uniqueDays !== days) {
+        throw new Error(`Incomplete month ${month}: ${uniqueDays}/${days} daily points available. ` +
+            `Monthly averages require every day of the calendar month.`);
+    }
+    const hashpriceUsdPh = mean(points.map((p) => p.hashprice_usd_ph_day));
+    // BTC hashprice per day = USD hashprice / BTC price of that same day
+    const hashpriceBtcPh = mean(points.map((p) => p.hashprice_usd_ph_day / p.btc_price_usd));
+    return {
+        month,
+        from,
+        to,
+        days,
+        btc_price_usd: round(mean(points.map((p) => p.btc_price_usd)), 2),
+        network_hashrate_eh: round(mean(points.map((p) => p.network_hashrate_eh)), 2),
+        hashprice_usd_ph_day: round(hashpriceUsdPh, 2),
+        hashprice_usd_th_day: round(hashpriceUsdPh / 1000, 5),
+        hashprice_btc_ph_day: round(hashpriceBtcPh, 8),
+        hashprice_sats_th_day: round((hashpriceBtcPh * 1e8) / 1000, 2),
+        methodology: {
+            period: "Full calendar month, UTC days",
+            btc_price: "Arithmetic mean of daily prices (daily price = last price recorded on the UTC day, ~UTC close)",
+            network_hashrate: "Arithmetic mean of daily network hashrate estimates",
+            hashprice_usd: "Arithmetic mean of daily USD hashprice (block subsidy + ~2% fee approximation)",
+            hashprice_btc: "Arithmetic mean of daily BTC hashprice (daily USD hashprice / daily BTC price)",
+        },
+    };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@startminingmcp/mcp",
+  "mcpName": "io.github.tibsp/startmining-mcp",
+  "version": "1.1.0",
+  "description": "MCP server for Bitcoin mining data - hashprice, difficulty, profitability calculations",
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "startmining-mcp": "./dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "bitcoin",
+    "mining",
+    "hashprice",
+    "cryptocurrency",
+    "ai",
+    "claude"
+  ],
+  "author": {
+    "name": "Thibaut Spanier",
+    "email": "thibaut@startmining.io",
+    "url": "https://startmining.io"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://pro.startmining.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TIBSP/startmining-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}