# gitbeacon-mcp

MCP server for **[GitBeacon](https://gitbeacon.dev)** — pay-per-call **GitHub trend
intelligence** for AI agents. Read the current daily LLM-analyzed digest of open-source
trends, poll for new digests, pull the top trending repos with full metadata, and walk
historical digests to see how trends evolved. Pay **per call** with USDC on **Base** via
**x402** — no signup, no accounts, no API keys.

- **4 free tools** — no wallet, no API key.
- **2 paid tools** — flat per-call USD prices, settled in USDC on **Base Mainnet** via x402.

Try before you pay: the free `get_sample` tool returns a frozen sample digest so you can
learn the exact response shape first.

---

## Quick start

### Free tier (no wallet)

```json
{
  "mcpServers": {
    "gitbeacon": {
      "command": "npx",
      "args": ["-y", "gitbeacon-mcp"]
    }
  }
}
```

You get `get_brief`, `get_index`, `get_sample`, `get_latest_digest`.

### Paid tier (with wallet)

Add an EVM wallet private key (0x-prefixed) that holds USDC on **Base Mainnet**:

```json
{
  "mcpServers": {
    "gitbeacon": {
      "command": "npx",
      "args": ["-y", "gitbeacon-mcp"],
      "env": { "PRIVATE_KEY": "0x..." }
    }
  }
}
```

The paid tools (`get_repos`, `get_digests`) then settle each call automatically.

### Install snippets

Claude Code:

```bash
claude mcp add gitbeacon -- npx -y gitbeacon-mcp
# with a wallet:
claude mcp add gitbeacon --env PRIVATE_KEY=0x... -- npx -y gitbeacon-mcp
```

Claude Desktop / Cursor: add the JSON block above to your MCP config
(`claude_desktop_config.json` or `.cursor/mcp.json`).

---

## Tools

### Free tools

| Tool | Endpoint | Description |
| --- | --- | --- |
| `get_brief` | `GET /v1/brief` | Field-trimmed snapshot of the current daily digest. |
| `get_index` | `GET /v1/index` | Poll target — digest id, digestDate, updatedAt, nextExpected. |
| `get_sample` | `GET /v1/sample` | Frozen sample digest for learning the response contract. |
| `get_latest_digest` | `GET /v1/digests/latest` | Most recent completed daily GitHub digest, full fields. |

### Paid tools

| Tool | Endpoint | Price (USD) | Description |
| --- | --- | --- | --- |
| `get_repos` | `GET /v1/repos` | **$0.01** | Top trending repos sorted by stars with full metadata. Optional `limit`, `language`. |
| `get_digests` | `GET /v1/digests` | **$0.05** | Historical daily digests tracking open-source trends over time. Optional `days` (1–30), `limit`. |

Prices are flat per call — **no bundles, no entitlements**. Confirm live prices any time
with `get_brief`/the site.

---

## How payments work (x402)

GitBeacon speaks the [x402](https://x402.org) `exact` scheme. The API's 402 advertises a
**Base** (USDC, EIP-3009) rail; this MCP settles on **Base**:

1. The MCP requests a paid endpoint. With no payment, the API replies **HTTP 402** with the
   accepted terms.
2. If `PRIVATE_KEY` is set, the MCP settles the call via the standard `@x402/fetch` V2
   client and retries. If no key is set, the MCP returns the **402 price terms** so you can
   see the cost without paying.
3. The API returns the data plus a `payment` block.

**Compute-first, settle-after:** GitBeacon computes the full answer **before** charging, so
you are never billed for an error.

No accounts, no API keys — just a wallet with USDC on **Base Mainnet**.

---

## Environment variables

| Variable | Required | Description |
| --- | --- | --- |
| `PRIVATE_KEY` | No | 0x-prefixed wallet key with **USDC on Base Mainnet**. Required to pay the 2 paid tools on a live API. Free tools work without it; without a key the paid tools surface the 402 price terms. |
| `GITBEACON_API_URL` | No | Override the API base URL (default `https://api.gitbeacon.dev`). |

---

## Disclaimer

GitBeacon provides **informational** GitHub trend data. It is provided as-is without
warranty. See <https://api.gitbeacon.dev/terms.txt>.

Docs for agents: <https://api.gitbeacon.dev/llms.txt> ·
full: <https://api.gitbeacon.dev/llms-full.txt>

---

## License

MIT © jcislo