Stacks AI ~ MCP Server

Comprehensive Model Context Protocol (MCP) server for the Stacks Bitcoin Layer 2 DeFi ecosystem. Part of the Stacks AI project, providing unified access to 6 major DeFi protocols with over 144+ professional tools for lending, trading, staking, and governance operations.

Table of Contents

• Overview

  • Stacks AI Ecosystem

  • Architecture Overview

• Supported Protocols

• Quick Start

  • Prerequisites

  • Installation

  • Environment Configuration

• Usage Examples

• Architecture

  • Plugin System

  • Core Components

  • Transaction Flow

• API Integration

• Development

• Testing

• Security Considerations

• MCP Protocol Compliance

• Troubleshooting

• Project Statistics

Overview

Stacks AI MCP Server enables AI agents and applications to interact with the entire Stacks DeFi ecosystem through a standardized protocol interface. It integrates with all major Bitcoin DeFi protocols on Stacks, enabling natural language interactions with Bitcoin DeFi.

Stacks AI Ecosystem

The Stacks AI project consists of two main components:

1. MCP Server (this repository) - Backend protocol integration exposing Bitcoin DeFi operations

2. Frontend (separate repository) - Chat-based user interface with Stacks wallet integration

Architecture Overview

Supported Protocols

Protocol Integration Map

ALEX Protocol

Automated Market Maker (AMM) and DEX with multi-hop routing capabilities.

Features:

• Multi-hop token swaps (1-4 pool routing)

• Liquidity pool operations

• Price feeds and market statistics

• TVL and volume analytics

• Flash loan integration

• 34 tools covering all AMM operations

Bitflow Protocol

Stable-focused DEX with keeper-based automation system.

Features:

• StableSwap and XYK pools

• Keeper-based automated execution

• BTC to sBTC bridge operations

• DCA (Dollar Cost Averaging) orders

• Group order management

• 29 tools for stable swaps and automation

Arkadiko Protocol

Multi-collateral lending platform with stablecoin minting.

Features:

• Collateralized debt positions (CDPs)

• USDA stablecoin minting

• Vault management and liquidations

• DEX operations and liquidity provision

• Governance proposals and voting

• DIKO token staking

• 28 tools for comprehensive DeFi operations

Charisma Protocol

Vault-based DEX with Blaze intent execution protocol.

Features:

• Composable vault routing

• Limit and triggered orders

• Blaze intent protocol execution

• Multihop swap routing

• API key management for automation

• 14 tools for advanced trading strategies

Velar Protocol

Multi-chain Bitcoin Layer-2 DEX.

Features:

• SDK-based swap routing

• Token pair management

• Price feeds and historical data

• Pool analytics and liquidity tracking

• Cross-chain token support

• 18 tools combining SDK and API operations

Granite Protocol

Bitcoin-native lending protocol with sBTC collateral.

Features:

• BTC-backed stablecoin borrowing

• Liquidity provision with yield

• LP token staking for rewards

• Liquidation operations

• Flash loans for advanced strategies

• Governance proposals

• 21 tools for complete lending operations

Quick Start

Prerequisites

• Claude Desktop application (or Cursor/VS Code with MCP support)

• Node.js 18 or higher

• pnpm package manager

• Stacks wallet (private key or mnemonic)

Installation

1. Clone and build the server

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

2. Configure environment variables

   cp .env.example .env

   Edit .env file with your wallet credentials and network preferences.

3. Automated Setup (Recommended)

   Use the automated setup script to configure your preferred AI application:

   # Interactive mode - choose which application to configure pnpm setup # Configure Claude Desktop only pnpm setup:claude # Configure Cursor editor only pnpm setup:cursor # Configure VS Code only pnpm setup:code # Configure multiple applications ./setup-mcp.sh --claude --cursor --code

   The setup script will:

   • Read your .env configuration

   • Generate the appropriate MCP configuration

   • Install it in the correct location for your chosen application(s)

   • Provide restart instructions

4. Manual Configuration (Alternative)

   If you prefer manual setup, you can configure the applications directly:

   Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json Cursor Editor: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-specific) VS Code: ~/Library/Application Support/Code/User/mcp.json (global) or .vscode/mcp.json (project-specific)

   The configuration format should look like:

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

5. Restart your AI application

   Close and reopen Claude Desktop, Cursor, or VS Code to load the MCP server.

Environment Configuration

Network Endpoints

• Testnet: https://api.testnet.hiro.so (development use)

• Mainnet: https://api.hiro.so (production use with real Bitcoin)

• Devnet: http://localhost:20443 (local development with Clarinet)

Usage Examples

Token Operations

Smart Contracts

Stacking (PoX) Operations

ALEX DEX Trading

Arkadiko Protocol

Charisma Protocol

Velar Protocol

Granite Lending

NFT Operations

Network Analytics

Protocol Integration Status

✅ Fully Integrated (Production Ready)

• Stacks Core: Contracts, Transactions, PoX, Tokens, NFTs, Blocks, Mempool, Events

• ALEX Protocol: AMM, Orderbook, Launchpad, Liquidity Pools

• Arkadiko Protocol: Vaults, USDA Stablecoin, DEX, Governance

• Charisma Protocol: Composable Vaults, Blaze Intent Protocol

• Velar Protocol: Multi-chain DEX, Liquidity, Price Feeds

• Granite Protocol: BTC Lending, sBTC Collateral

⏸️ Requires API Keys

• BitFlow Protocol: Stable DEX operations (requires BitFlow team API access)

  • Contact BitFlow via their documentation for API key access

  • Can be re-enabled after obtaining keys by uncommenting in src/index.ts

Configuration

Required Environment Variables

• STACKS_NETWORK: Network to connect to (mainnet, testnet, or devnet)

• WALLET_PRIVATE_KEY or WALLET_MNEMONIC: Wallet credentials (provide one)

Optional Environment Variables

• HIRO_API_KEY: API key for higher rate limits with Hiro APIs

• STACKS_MAINNET_API_URL: Custom mainnet API endpoint

• STACKS_TESTNET_API_URL: Custom testnet API endpoint

• STACKS_DEVNET_API_URL: Custom devnet API endpoint

• MCP_SERVER_HOST: Server host for HTTP mode (default: localhost)

• MCP_SERVER_PORT: Server port for HTTP mode (default: 3000)

• NODE_ENV: Environment mode (development, production, test)

• LOG_LEVEL: Logging level (info, debug, error)

• DEBUG: Enable debug mode (true/false)

• DISABLE_TELEMETRY: Disable telemetry (true/false)

See .env.example for detailed configuration options.

Usage

Development Mode

Run the server with auto-reload:

Production Build

Build and run the server:

Testing

Run all tests:

Run Clarinet integration tests:

Run tests in watch mode:

Type Checking

Verify TypeScript types:

Linting

Check code quality:

Architecture

Plugin-Based System

The server uses a modular plugin architecture where each DeFi protocol is implemented as an independent plugin:

Plugin System Architecture

Core Components

Transaction Flow

Data Flow

Tool Categories

Core Stacks Operations

• Contract deployment and interaction

• Transaction queries and tracking

• STX transfers and stacking

• Account and balance management

• Block and network information

• Mempool statistics and fee estimation

DeFi Protocol Operations

• Token swaps and liquidity provision

• Lending and borrowing operations

• Vault and collateral management

• Staking and reward claiming

• Governance voting and proposals

• Flash loan execution

Read Operations

All protocols support comprehensive read operations:

• Price feeds and market data

• Pool statistics and analytics

• Position tracking and health

• Historical data and trends

• Protocol parameters and state

Write Operations

All protocols support transaction execution:

• Swap execution with routing

• Liquidity addition and removal

• Borrow and repay operations

• Collateral management

• Staking and unstaking

• Proposal creation and voting

API Integration

The server integrates with multiple data sources:

• Hiro Stacks API: Core blockchain data and transactions

• ALEX API: DEX statistics and market data

• Velar SDK & API: Token swaps and pool information

• Bitflow SDK: StableSwap operations and keeper automation

• Pyth Network: Price oracle data for Granite

• Direct Contract Calls: Real-time on-chain data

Integration Architecture

API Integration Patterns

Each protocol plugin follows a consistent integration pattern:

Security Considerations

Private Key Management

• Never commit .env files to version control

• Use environment-specific wallets (testnet for development)

• Rotate keys regularly in production environments

• Consider using hardware wallets for high-value operations

Transaction Safety

• All transactions return unsigned contract call parameters

• Client applications must handle transaction signing

• Post-conditions can be added for additional security

• Test all operations on testnet before mainnet deployment

Rate Limiting

• Use HIRO_API_KEY for higher rate limits

• Implement client-side request throttling

• Cache frequently accessed data when possible

• Monitor API usage to avoid rate limit issues

Development

Development Workflow

Testing Strategy

Adding New Tools

1. Create service class with protocol integration:

2. Create plugin extending PluginBase:

3. Register plugin in main index:

Code Standards

• TypeScript for type safety

• Zod for runtime validation

• No mock data in production code

• Comprehensive error handling

• Professional documentation

• GPG-signed commits

MCP Protocol Compliance

This server implements the Model Context Protocol specification:

• Tool Discovery: ListToolsRequest returns all available tools

• Tool Execution: CallToolRequest executes tools with validation

• Standard Transport: Uses stdio for communication with MCP clients

• Structured Responses: All responses follow MCP format

• Error Handling: Proper error codes and messages

MCP Communication Flow

Tool Schema Example

Each tool follows a consistent schema pattern:

Troubleshooting

Common Issues

Server fails to start:

• Verify .env file exists and contains required variables

• Check that wallet credentials are valid

• Ensure Node.js version is 20.x or higher

Transaction failures:

• Verify sufficient STX balance for fees

• Check that wallet has required token approvals

• Confirm network selection matches wallet network

API rate limiting:

• Add HIRO_API_KEY to .env for higher limits

• Implement request throttling in client applications

• Use caching for frequently accessed data

Type errors during build:

• Run pnpm install to ensure dependencies are current

• Clear node_modules and reinstall if issues persist

• Verify TypeScript version is 5.x

Contributing

Contributions are welcome. Please ensure:

• All tests pass (pnpm test)

• Type checking succeeds (pnpm type-check)

• Code follows existing patterns

• Documentation is updated

• Commits are GPG-signed

License

MIT License - see LICENSE file for details

Acknowledgments

Special thanks to:

• Stacks Foundation for the Bitcoin L2 infrastructure

• Hiro Systems for comprehensive blockchain APIs

• ALEX, Bitflow, Arkadiko, Charisma, Velar, and Granite teams for protocol documentation

• Model Context Protocol team for the MCP specification

Support

For issues, questions, or contributions:

• Create an issue in the repository

• Review documentation in /docs directory

• Check protocol-specific documentation for integration details

Project Statistics

Coverage Overview

Protocol Integration Status

System Architecture Stats

• Total Protocols: 7 (6 DeFi + Stacks Core)

• Total Tools: 144+

• Plugin System: Modular, extensible

• Network Support: Mainnet, Testnet, Devnet

• Wallet Support: Private Key, Mnemonic

• AI Platforms: Claude Desktop, Cursor, VS Code

• Testing: Unit + Integration (Clarinet)

• Type Safety: Full TypeScript with Zod validation

Technology Stack

Key Features

• Comprehensive Protocol Coverage: All major Stacks DeFi protocols in one unified interface

• Real Implementation: No mocks, all tools interact with actual protocols and smart contracts

• Type Safety: Full TypeScript with runtime Zod validation for reliability

• Modular Architecture: Plugin-based system allows easy addition of new protocols

• Multiple Networks: Support for mainnet, testnet, and local devnet

• Professional Standards: GPG-signed commits, comprehensive documentation, no mock data

• AI-First Design: Natural language interactions with Bitcoin DeFi

• Security Focused: Safe transaction handling with user-controlled signing

Version

Current version: 1.0.0

Last updated: October 2025

Summary

Stacks AI MCP Server is the first comprehensive Model Context Protocol server for the Bitcoin DeFi ecosystem, built on Stacks Layer 2. With 144+ professional tools across 7 protocol integrations, it enables AI agents and applications to interact with Bitcoin DeFi through natural language interfaces.

The server implements real protocol integration without mocks, uses a modular plugin architecture for extensibility, and follows professional development standards including full TypeScript type safety, GPG-signed commits, and comprehensive testing.

This project demonstrates how AI can make Bitcoin DeFi accessible to everyone through conversational interfaces, bridging the gap between complex blockchain operations and natural language interactions.