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

Related MCP server: Stacks AI MCP Server

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

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

Food Tiers

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