Stacks AI

Stacks AI MCP Server provides a unified Model Context Protocol interface to interact with the Stacks Bitcoin Layer 2 DeFi ecosystem. It exposes 144+ tools across multiple DeFi protocols, enabling AI agents and applications to perform lending, trading, staking, governance, and other operations through a standardized MCP workflow.

How to use

You interact with the MCP Server through an MCP client (Claude Desktop, Cursor, or VS Code) to discover available tools, execute operations, and receive structured responses. Start by connecting your MCP client to your local MCP server configuration. The server presents a catalog of tools from all integrated protocols and executes the requested tool after validating parameters. You then sign and broadcast any resulting transactions from your wallet, and you can query the status of those transactions from the MCP client. Use natural language prompts to perform complex DeFi actions such as swaps, vault operations, stacking, and governance proposals without writing contract calls directly.

How to install

Prerequisites are in place so you can run the MCP Server locally. Install and run the server in a sequence that matches the following steps.

1. Clone the MCP server repository and install dependencies.

git clone <repository-url>
cd stacks-mcp-server
pnpm install

2. Build the server.

pnpm build

3. Prepare environment configuration. Copy the example environment file and edit it with wallet credentials and network preferences.

cp .env.example .env

4. Start the MCP server in development or production mode using the available start commands.

pnpm dev

Additional sections

Configuration and environment details are required to run the MCP server. The following environment variables are commonly used, and you should tailor them to your setup.

# Example environment values
WALLET_PRIVATE_KEY=0xYOURPRIVATEKEY
STACKS_NETWORK=mainnet
STACKS_MAINNET_API_URL=https://api.hiro.so
STACKS_TESTNET_API_URL=https://api.testnet.hiro.so
HIRO_API_KEY=your_hiro_api_key
BITFLOW_API_KEY=your_bitflow_api_key

For a local, stdio-based runtime, you can run the MCP server with Node and point the client to the built index. Use the exact command and path shown in the configuration example.

{
  "mcpServers": {
    "stacks_mcp": {
      "command": "node",
      "args": ["/absolute/path/to/stacks-mcp-server/dist/index.js"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x1234...",
        "STACKS_NETWORK": "mainnet",
        "STACKS_MAINNET_API_URL": "https://api.hiro.so",
        "STACKS_TESTNET_API_URL": "https://api.testnet.hiro.so",
        "HIRO_API_KEY": "your_hiro_api_key"
      }
    }
  }
}

Available tools

swap_tokens

Execute token swaps on the ALEX protocol with multi-hop routing and liquidity management

add_liquidity

Provide liquidity to pools across supported protocols and view pool analytics

deploy_contract

Deploy and interact with Clarity smart contracts on the Stacks network

call_contract

Call functions on deployed Clarity contracts and read on-chain state

mint_usda

Mint USDA stablecoins via Arkadiko vaults and manage vault health

delegate_stx

Delegate STX for PoX stacking and check stacking status

blaze_intent

Execute Blaze intents for Charisma vault routing and automated trading patterns

cross_chain_swap

Perform cross-chain swaps via Velar multi-chain DEX integration

lend_borrow

Lend or borrow assets via Granite BTC lending protocols and manage collateral

stake_rewards

Claim or manage staking rewards and PoX statistics

vote_proposal

Submit or vote on governance proposals across protocols