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