bitbadges-builder-mcp

BitBadges Builder MCP Server

MCP (Model Context Protocol) server for building, auditing, and querying BitBadges collections via AI. Works with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client.

This MCP server does not sign or broadcast transactions. It builds transaction JSON that your application signs and broadcasts using your own wallet/signer.

Quick Start

1. Install

npm install -g bitbadges-builder-mcp

Or use npx (no install needed):

npx bitbadges-builder-mcp

2. Configure Your MCP Client

Claude Desktop (~/.config/claude/config.json):

{
  "mcpServers": {
    "bitbadges-builder": {
      "command": "npx",
      "args": ["bitbadges-builder-mcp"],
      "env": {
        "BITBADGES_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code (.mcp.json in project root):

{
  "mcpServers": {
    "bitbadges-builder": {
      "command": "npx",
      "args": ["bitbadges-builder-mcp"],
      "env": {
        "BITBADGES_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor (Settings > MCP Servers > Add):

{
  "command": "npx",
  "args": ["bitbadges-builder-mcp"],
  "env": {
    "BITBADGES_API_KEY": "your-api-key-here"
  }
}

3. Get an API Key

Get your free API key at: https://bitbadges.io/developer

The API key enables query tools (see below). Builder, validation, and knowledge tools work without an API key.

4. Start Building

"Create a 1000-supply NFT collection with 5 BADGE mint price"

"Build a USDC stablecoin vault with 100/day withdraw limit"

"Explain collection 123 to me"

"Audit this collection for security risks"

Environment Variables

Variable	Required	Description
BITBADGES_API_KEY	For query tools	API key from https://bitbadges.io/developer

No wallet, mnemonic, or private key is needed. This server builds transaction JSON only — your app handles signing and broadcasting.

How It Works

You describe what you want
    ↓
MCP builds transaction JSON (MsgUniversalUpdateCollection, MsgTransferTokens, etc.)
    ↓
audit_collection catches security issues
    ↓
validate_transaction checks JSON format
    ↓
You sign with your wallet (MetaMask, Keplr, SDK, etc.) and broadcast

Available Tools

Validation & Analysis (no API key needed)

Tool	Description
validate_transaction	Validate transaction JSON against critical rules
audit_collection	Audit for security risks, design flaws, supply inflation vectors
explain_collection	Generate human-readable markdown explanation of a collection

Builders (no API key needed)

Tool	Description
build_token	Universal token builder — any collection type from design axes
build_smart_token	IBC-backed smart token (stablecoin, wrapped asset)
build_fungible_token	ERC-20 style fungible token
build_nft_collection	NFT collection with minting config
build_address_list	On-chain address list (manager add/remove)
build_claim	Build claim JSON for the API (code-gated, password-gated, whitelist-gated, open)

Components (no API key needed)

Tool	Description
generate_backing_address	Compute deterministic IBC backing address from denom
generate_approval	Build approval structures by type
generate_permissions	Build permission presets
generate_alias_path	Build alias path for liquidity pools

Utilities (no API key needed)

Tool	Description
convert_address	Convert between ETH (0x) and BitBadges (bb1) formats
validate_address	Check if address is valid and detect chain type
lookup_token_info	Get token symbol, denom, decimals, backing address
get_current_timestamp	Get current time with optional offsets

Knowledge (no API key needed)

Tool	Description
get_skill_instructions	Get detailed instructions for a specific skill
search_knowledge_base	Search docs, learnings, recipes, error patterns
diagnose_error	Diagnose transaction errors and suggest fixes
fetch_docs	Fetch live documentation from docs.bitbadges.io

Query Tools (require API key)

Tool	Description
query_collection	Fetch collection details with field filtering
query_balance	Check token balance for an address
simulate_transaction	Dry-run transaction for validity and gas estimation
verify_ownership	Verify if address meets AND/OR/NOT ownership requirements
search	Search collections, accounts, and tokens
search_plugins	Search claim plugins or fetch by ID
analyze_collection	Query and produce structured collection analysis
build_transfer	Auto-query collection and build MsgTransferTokens
build_dynamic_store	Build dynamic store operations (create, update, set values)
query_dynamic_store	Query dynamic store values and metadata

Resources

The MCP server exposes these resources that clients can read for context:

Resource URI	Description
bitbadges://rules/critical	Critical rules for building transactions
bitbadges://tokens/registry	Token registry (symbol, denom, decimals)
bitbadges://skills/all	All skill instructions
bitbadges://docs/concepts	Conceptual documentation
bitbadges://docs/examples	Example transactions and patterns
bitbadges://recipes/all	Code recipes and decision matrices
bitbadges://learnings/all	Known gotchas, tips, and discoveries
bitbadges://errors/patterns	Error patterns and diagnostics
bitbadges://workflows/all	Step-by-step workflow chains
bitbadges://schema/token-builder	Token builder schema reference
bitbadges://docs/frontend	Reference frontend patterns

Skills

Skills are detailed instruction sets loaded on-demand via get_skill_instructions(skillId):

Skill ID	Description
smart-token	IBC-backed smart token with 1:1 backing
fungible-token	ERC-20 style fungible token
nft-collection	NFT collection design and minting
subscription	Time-dependent subscription token
bb-402	Token-gated API access (HTTP 402 pattern)
ai-criteria-gate	AI agent as criteria verifier
minting	Minting strategies (public, manager, pricing)
custom-2fa	Custom 2FA requirements
immutability	Lock permissions and immutability patterns
liquidity-pools	Swappable tokens and trading
payment-protocol	Payment and pricing mechanisms
verified	Verified credential gates
tradable	Marketplace trading configuration
address-list	On-chain address list collections

Supported Tokens

Symbol	IBC Denom	Decimals
BADGE	ubadge (Cosmos) / abadge (EVM)	9 / 18
USDC	ibc/F082B65...	6
ATOM	ibc/A4DB47...	6
OSMO	ibc/ED07A3...	6

Signing & Broadcasting (Your Responsibility)

This MCP server returns unsigned transaction JSON. To submit on-chain:

Browser (EVM wallet like MetaMask):

• Call EVM precompiles using ethers.js / viem with the transaction data

Browser (Cosmos wallet like Keplr):

• Use Keplr's signDirect with the transaction's SignDoc

Server-side (SDK):

import { GenericEvmAdapter, GenericCosmosAdapter } from 'bitbadgesjs-sdk';

// EVM path (recommended for server-side)
const adapter = GenericEvmAdapter.fromPrivateKey(key, 'https://evm-rpc.bitbadges.io');

// Cosmos path
const adapter = GenericCosmosAdapter.fromPrivateKey(key, 'bitbadges_50024-1');

// Sign and broadcast
const result = await adapter.signAndBroadcast(messages, fee, memo);

See BitBadges SDK docs for full signing documentation.

Related Tools

Tool	Install	Description
BitBadges MCP (this)	npm i -g bitbadges-builder-mcp	AI-powered collection builder, auditor, and explainer
BitBadges SDK	npm i bitbadgesjs-sdk	TypeScript SDK for API, signing, address conversion
BitBadges API	https://bitbadges.io/developer	REST API for querying collections, balances, ownership
BitBadges Docs	https://docs.bitbadges.io	Full documentation
BitBadges Explorer	https://explorer.bitbadges.io	On-chain explorer

Local Development

git clone https://github.com/bitbadges/bitbadges-builder-mcp.git
cd bitbadges-builder-mcp
npm install
npm run build
npm run dev    # Run with tsx (hot reload)
npm test       # Run tests

License

MIT