Bluepages MCP Server

MCP server for Bluepages — crypto address ↔ identity and label lookups.

6M+ addresses linked to 4M+ social accounts and 4,800+ labeled wallets across 30+ sources. Identities span 10+ platforms (Twitter/X, Farcaster, GitHub, Discord, Telegram, email, and more). Lookups also return address labels (CEX wallets, exchanges), sanctions screening (OFAC and other lists), and cluster detection. Supports ETH, BTC, SOL, TRON, XMR, TON, Celestia, and XRP addresses.

Quick start

npx -y github:bluepagesdoteth/bluepages-mcp

Requires either:

• BLUEPAGES_API_KEY — get one at bluepages.fyi/api-keys (recommended, 20% cheaper)
• PRIVATE_KEY — Ethereum private key for x402 pay-per-request (USDC on Base)

Setup

Add to your MCP client's config (see MCP clients for where each client stores this):

{
  "mcpServers": {
    "bluepages": {
      "command": "npx",
      "args": ["-y", "github:bluepagesdoteth/bluepages-mcp"],
      "env": {
        "BLUEPAGES_API_KEY": "your_key_here",
        "PRIVATE_KEY": "your_eth_private_key_here"
      }
    }
  }
}

Claude Code users: install the plugin instead — no manual config needed.

Tools

Development

pnpm install
pnpm test            # unit + stdio integration tests (node:test, no network)
pnpm format          # prettier

Formatting logic lives in src/lib.js; src/mcp-server.js wires it to the MCP transport and the live API.

When the private bluepages-fyi repo is checked out as a sibling directory, contract.test.js additionally validates the test fixtures against its Zod response schemas (drift tripwire); elsewhere it auto-skips.

CI and signoff

CI (.github/workflows/test.yml) runs the hermetic suite on GitHub-hosted runners, where the contract tests self-skip (no bluepages-fyi there). The contract tests are enforced locally via gh-signoff — run the suite on a dev machine and post the green check yourself:

gh extension install basecamp/gh-signoff   # once
pnpm run signoff                           # preflight → strict suite → gh signoff

pnpm run signoff starts with a preflight (pnpm run signoff:doctor) that checks every prerequisite in one pass — Node ≥ 21, the bluepages-fyi sibling checkout, its installed deps (the contract schemas import zod), gh auth, the gh-signoff extension — and lists all missing pieces with their fix commands, instead of failing serially. pnpm run signoff:doctor --fix additionally self-heals the deps step (pnpm install --prod --ignore-scripts in the sibling; skips the native better-sqlite3 build).

The suite then runs with CONTRACT_REQUIRED=1: if bluepages-fyi is not checked out as a sibling (schemas unavailable), the run fails instead of skipping the contract tests — a signoff always attests a full run, whatever the preflight said. Plain pnpm test keeps the graceful skip for consumers outside the workspace.

Make signoff a required status check on main (repo settings → Branches, one-time) so merges require a local run. A husky pre-push hook also runs pnpm test as a safety net.

License

MIT