@crbonfree/mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crbon Labs Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+<p align="center">
+  <strong>@crbonfree/mcp</strong>
+</p>
+
+<p align="center">
+  Give your AI agent eyes on your carbon footprint.<br />
+  Ask questions in natural language. Get real emissions data back.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@crbonfree/mcp"><img src="https://img.shields.io/npm/v/@crbonfree/mcp.svg?style=flat-square" alt="npm" /></a>
+  <a href="https://github.com/Crbon-Labs-Inc/crbonfree-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="MIT" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-047857.svg?style=flat-square" alt="MCP" /></a>
+  <a href="https://beta.crbonfree.com"><img src="https://img.shields.io/badge/CrbonFree-beta-047857.svg?style=flat-square" alt="CrbonFree" /></a>
+</p>
+
+<br />
+
+> *"How much CO₂ did my AI usage produce this month?"*
+>
+> *"Which models are my biggest emitters?"*
+>
+> *"Show me my carbon retirement receipts."*
+
+Works with **Claude Desktop** &nbsp;·&nbsp; **Cursor** &nbsp;·&nbsp; **Claude Code** &nbsp;·&nbsp; **Windsurf** &nbsp;·&nbsp; any MCP client
+
+---
+
+## Get started in 2 minutes
+
+### 1. Grab an API key
+
+[CrbonFree dashboard](https://beta.crbonfree.com) → **API Keys** → **Create API Key**
+
+The key starts with `ck_live_` and is shown once — copy it immediately. New to CrbonFree? [Sign up free.](https://crbonfree.com)
+
+### 2. Pick your client
+
+<details open>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "crbonfree": {
+      "command": "npx",
+      "args": ["-y", "@crbonfree/mcp"],
+      "env": {
+        "CRBONFREE_API_KEY": "ck_live_..."
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "crbonfree": {
+      "command": "npx",
+      "args": ["-y", "@crbonfree/mcp"],
+      "env": {
+        "CRBONFREE_API_KEY": "ck_live_..."
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude mcp add crbonfree -- npx -y @crbonfree/mcp
+```
+
+Then set the env var:
+```bash
+export CRBONFREE_API_KEY="ck_live_..."
+```
+</details>
+
+<details>
+<summary><strong>Windsurf / Other</strong></summary>
+
+Any MCP-compatible client works:
+
+```
+command: npx
+args: ["-y", "@crbonfree/mcp"]
+env: { CRBONFREE_API_KEY: "ck_live_..." }
+```
+</details>
+
+### 3. Ask away
+
+That's it. Your agent now has 6 tools:
+
+---
+
+## Tools
+
+| | Tool | What you can ask |
+|---|------|-----------------|
+| **Measure** | `get_emissions_summary` | *"How much CO₂ did my AI usage produce in May?"* |
+| **Analyze** | `get_usage_breakdown` | *"Which models are my biggest carbon emitters?"* |
+| **Organize** | `list_projects` | *"What projects am I tracking?"* |
+| **Prove** | `list_carbon_receipts` | *"Show me my carbon retirement receipts"* |
+| **Inspect** | `get_carbon_receipt` | *"Get the details for receipt abc-123"* |
+| **Status** | `get_retirement_status` | *"What's my current retirement status?"* |
+
+All tools are **read-only**. No mutations, no deletions, no billing changes.
+
+<details>
+<summary><strong>Filtering options</strong></summary>
+
+`get_emissions_summary` and `get_usage_breakdown` accept optional filters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `start_date` | `string` | Start date (`YYYY-MM-DD`). Defaults to 30 days ago. |
+| `end_date` | `string` | End date (`YYYY-MM-DD`). Defaults to today. |
+| `project_id` | `string` | Scope to a specific project. |
+
+</details>
+
+---
+
+## How it works
+
+```
+Your AI agent ←── stdio (JSON-RPC) ──→ @crbonfree/mcp ──→ CrbonFree API
+                                           │
+                                    reads CRBONFREE_API_KEY
+                                    from environment
+```
+
+The server reads your API key from the environment and sends it as an `X-API-Key` header on every request. If the key is missing, the server exits immediately with a clear error — no silent 401s.
+
+---
+
+## TypeScript SDK
+
+Building something programmatic? Use [`@crbonfree/sdk`](https://www.npmjs.com/package/@crbonfree/sdk) — the same typed client that powers this MCP server, available directly in your code.
+
+---
+
+<p align="center">
+  <a href="https://beta.crbonfree.com">Dashboard</a> &nbsp;·&nbsp;
+  <a href="https://www.npmjs.com/package/@crbonfree/sdk">SDK</a> &nbsp;·&nbsp;
+  <a href="https://github.com/Crbon-Labs-Inc/crbonfree-mcp/issues">Issues</a> &nbsp;·&nbsp;
+  <a href="https://crbonfree.com">Website</a>
+</p>
+
+<p align="center">
+  <sub>MIT — Crbon Labs Inc.</sub>
+</p>

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+import { CarbonLabsClient } from '@crbonfree/sdk';
+export declare const client: CarbonLabsClient;

package/dist/client.js

@@ -0,0 +1,10 @@
+import { CarbonLabsClient } from '@crbonfree/sdk';
+const apiKey = process.env.CRBONFREE_API_KEY;
+if (!apiKey) {
+    console.error('CRBONFREE_API_KEY environment variable is required.');
+    console.error('Get one from your CrbonFree dashboard: POST /api/v1/api-keys');
+    process.exit(1);
+}
+export const client = new CarbonLabsClient({
+    headers: { 'X-API-Key': apiKey },
+});

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerGetEmissionsSummary } from './tools/get-emissions-summary.js';
+import { registerGetUsageBreakdown } from './tools/get-usage-breakdown.js';
+import { registerListProjects } from './tools/list-projects.js';
+import { registerListCarbonReceipts } from './tools/list-carbon-receipts.js';
+import { registerGetCarbonReceipt } from './tools/get-carbon-receipt.js';
+import { registerGetRetirementStatus } from './tools/get-retirement-status.js';
+const server = new McpServer({
+    name: 'crbonfree',
+    version: '0.1.0',
+});
+registerGetEmissionsSummary(server);
+registerGetUsageBreakdown(server);
+registerListProjects(server);
+registerListCarbonReceipts(server);
+registerGetCarbonReceipt(server);
+registerGetRetirementStatus(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('MCP server error:', error);
+    process.exit(1);
+});

package/dist/tools/get-carbon-receipt.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGetCarbonReceipt(server: McpServer): void;

package/dist/tools/get-carbon-receipt.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { client } from '../client.js';
+export function registerGetCarbonReceipt(server) {
+    server.registerTool('get_carbon_receipt', {
+        title: 'Get Carbon Receipt',
+        description: 'Fetch full details of a single carbon retirement receipt by ID. This retrieves the receipt — it does NOT verify it cryptographically.',
+        inputSchema: {
+            id: z.string().describe('The receipt ID (UUID).'),
+        },
+    }, async ({ id }) => {
+        try {
+            const result = await client.billing.getReceipt({ id });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ ...result, _summary: `Receipt ${id} fetched.` }, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: message, _summary: `Error: ${message}` }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/get-emissions-summary.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGetEmissionsSummary(server: McpServer): void;

package/dist/tools/get-emissions-summary.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { client } from '../client.js';
+export function registerGetEmissionsSummary(server) {
+    server.registerTool('get_emissions_summary', {
+        title: 'Get Emissions Summary',
+        description: 'Get total CO2 emissions, token usage, per-model rollups, and daily chart for a date range. Optionally filter by project.',
+        inputSchema: {
+            start_date: z.string().optional().describe('Start date (YYYY-MM-DD). Defaults to 30 days ago.'),
+            end_date: z.string().optional().describe('End date (YYYY-MM-DD). Defaults to today.'),
+            project_id: z.string().optional().describe('Filter to a specific project ID.'),
+        },
+    }, async ({ start_date, end_date, project_id }) => {
+        try {
+            const result = await client.telemetry.getSummary({ start_date, end_date, project_id });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ ...result, _summary: `Emissions summary: ${result?.data?.total_co2_kg ?? 'N/A'} kg CO2 (${result?.data?.total_tokens ?? 'N/A'} tokens)` }, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: message, _summary: `Error: ${message}` }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/get-retirement-status.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGetRetirementStatus(server: McpServer): void;

package/dist/tools/get-retirement-status.js

@@ -0,0 +1,25 @@
+import { client } from '../client.js';
+export function registerGetRetirementStatus(server) {
+    server.registerTool('get_retirement_status', {
+        title: 'Get Retirement Status',
+        description: 'Get the current billing period including total CO2, credits retired, and period status.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            const result = await client.billing.getCurrentPeriod();
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ ...result, _summary: 'Current billing period returned.' }, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: message, _summary: `Error: ${message}` }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/get-usage-breakdown.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGetUsageBreakdown(server: McpServer): void;

package/dist/tools/get-usage-breakdown.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { client } from '../client.js';
+export function registerGetUsageBreakdown(server) {
+    server.registerTool('get_usage_breakdown', {
+        title: 'Get Usage Breakdown',
+        description: 'Get per-model token/cost/carbon/energy breakdown for a date range. Optionally filter by project.',
+        inputSchema: {
+            range: z.enum(['7d', '30d', '90d', '365d']).optional().describe('Preset range. Ignored when start_date/end_date are provided.'),
+            start_date: z.string().optional().describe('Start date (YYYY-MM-DD).'),
+            end_date: z.string().optional().describe('End date (YYYY-MM-DD).'),
+            project_id: z.string().optional().describe('Filter to a specific project ID.'),
+        },
+    }, async ({ range, start_date, end_date, project_id }) => {
+        try {
+            const result = await client.usage.getBreakdown({
+                range,
+                startDate: start_date,
+                endDate: end_date,
+                projectId: project_id,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ ...result, _summary: 'Per-model usage breakdown returned.' }, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: message, _summary: `Error: ${message}` }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/list-carbon-receipts.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerListCarbonReceipts(server: McpServer): void;

package/dist/tools/list-carbon-receipts.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { client } from '../client.js';
+export function registerListCarbonReceipts(server) {
+    server.registerTool('list_carbon_receipts', {
+        title: 'List Carbon Receipts',
+        description: 'List carbon retirement receipts (paginated). Returns serial numbers, dates, and amounts.',
+        inputSchema: {
+            page: z.number().optional().describe('Page number (1-based).'),
+            limit: z.number().optional().describe('Number of receipts per page.'),
+        },
+    }, async ({ page, limit }) => {
+        try {
+            const result = await client.billing.listReceipts({ page, limit });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ ...result, _summary: 'Carbon receipts list returned.' }, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: message, _summary: `Error: ${message}` }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/list-projects.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerListProjects(server: McpServer): void;

package/dist/tools/list-projects.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { client } from '../client.js';
+export function registerListProjects(server) {
+    server.registerTool('list_projects', {
+        title: 'List Projects',
+        description: 'List projects (workspaces) in the active organization. Optionally include per-project usage stats.',
+        inputSchema: {
+            include: z.enum(['usage']).optional().describe('Pass "usage" to include per-project usage stats.'),
+            limit: z.number().optional().describe('Maximum number of projects to return.'),
+        },
+    }, async ({ include, limit }) => {
+        try {
+            const result = await client.projects.list({ include, limit });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ ...result, _summary: 'Project list returned.' }, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: message, _summary: `Error: ${message}` }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@crbonfree/mcp",
+  "version": "0.1.1",
+  "description": "MCP server for the CrbonFree carbon-offset API",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "crbonfree-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@crbonfree/sdk": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}