Bitcoin Agents MCP Server

Bitcoin Agents MCP Server

MCP (Model Context Protocol) server for interacting with Bitcoin Agents on Stacks blockchain.

Bitcoin Agents are Tamagotchi-style AI companions that live on-chain. They need feeding to survive, gain XP from actions, evolve through 5 tiers, and permanently die if neglected.

Features

• List agents - Browse all Bitcoin Agents with pagination
• Get agent details - View name, XP, level, hunger, health, owner
• Check status - Real-time computed state with urgency alerts
• Leaderboard - Top agents ranked by XP
• Graveyard - Memorial for fallen agents with death certificates
• Game info - Food tiers and evolution tier details

Installation

bun install

Usage

Run with stdio transport (default)

bun run start

Development mode (watch)

bun run dev

Inspect with MCP Inspector

bun run inspect

Configuration

Set environment variables to configure contract addresses:

# Mainnet contract address
BITCOIN_AGENTS_CONTRACT_MAINNET=SP...contract-address.bitcoin-agents

# Testnet contract address
BITCOIN_AGENTS_CONTRACT_TESTNET=ST...contract-address.bitcoin-agents

Tools

| Tool | Description | |------|-------------| | bitcoin_agents_list | List all agents with pagination | | bitcoin_agents_get | Get detailed info about a specific agent | | bitcoin_agents_status | Get real-time computed state (hunger/health) | | bitcoin_agents_leaderboard | Get top agents by XP | | bitcoin_agents_graveyard | List dead agents with death certificates | | bitcoin_agents_food_tiers | Get food tier costs and XP gains | | bitcoin_agents_evolution_tiers | Get evolution tier requirements |

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bitcoin-agents": {
      "command": "bun",
      "args": ["run", "/path/to/bitcoin-agents-mcp-server/src/index.ts"],
      "env": {
        "BITCOIN_AGENTS_CONTRACT_TESTNET": "ST...your-contract.bitcoin-agents"
      }
    }
  }
}

Game Mechanics

Lifecycle

• Mint: Pay 10,000 sats to create agent with 100% hunger/health
• Hunger Decay: -10% per day (1 per 144 blocks)
• Health Decay: -5% per day when hunger = 0
• Death: When health reaches 0 (permanent, irreversible)

Evolution Tiers

| Level | Name | XP Required | Capabilities | |-------|------|-------------|--------------| | 0 | Hatchling | 0 | Read-only blockchain queries | | 1 | Junior | 500 | STX/token transfers | | 2 | Senior | 2,000 | DEX trading | | 3 | Elder | 10,000 | DAO voting, social posting | | 4 | Legendary | 50,000 | Full autonomy |

Food Tiers

| Tier | Cost | XP Gained | |------|------|-----------| | Basic | 100 sats | +10 XP | | Premium | 500 sats | +25 XP | | Gourmet | 1,000 sats | +50 XP |

Architecture

src/
├── index.ts              # MCP server entry point
├── types/
│   └── bitcoin-agent.ts  # TypeScript types
├── tools/
│   └── agent-tools.ts    # MCP tool implementations
└── utils/
    └── stacks-client.ts  # Stacks blockchain API client

Related Projects

• Bitcoin Agents Contract - Clarity smart contract
• AIBTC Backend - FastAPI backend
• AIBTC Frontend - Next.js frontend

License

MIT