Stacks Clarity MCP Server

A comprehensive MCP (Model Context Protocol) server for Stacks blockchain development, providing 30+ specialized tools for Clarity smart contracts, SIP compliance, security, and performance optimization.

💡 New to MCP? Check out our integration guides for step-by-step setup instructions for Cursor, Claude Code, or local development.

🚀 Overview

This comprehensive MCP server provides a complete Stacks development toolkit, implementing TIER 1 and TIER 2 priorities for professional Stacks dApp development with security-first patterns and SIP compliance.

Key Features

• 🏗️ Complete SIP Standards Access - All 30+ SIP standards with full Clarity code
• 🔐 Security-First Development - Mandatory post-conditions for all token transfers
• ⚡ SIP-012 Performance Optimization - 2x database capacity and dynamic storage
• 🎨 Token Standards - Full SIP-009 (NFT) and SIP-010 (FT) implementations
• 🧪 Comprehensive Testing - Unit, integration, and security test generation
• 🔧 Clarinet Integration - Complete project setup and management tools
• 💰 Account Management - STX balances, transaction history, and validation
• 📚 Complete Documentation - Clarity Book, SIP standards, and integration guides

📋 Prerequisites

• Node.js and npm (npm ≥ 5.2.0)
• Clarinet CLI (for contract development)
• Stacks wallet (for frontend integration)
• Cursor IDE or Claude Code (for MCP integration)

🛠️ Quick Setup for Cursor/Claude Code

Option 1: Use Published Package (When Available)

Once published to npm, create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "stacks-clarity-mcp": {
      "command": "npx",
      "args": ["-y", "@stacks/stacks-clarity-mcp"],
      "env": {
        "HIRO_API_KEY": "",
        "STACKS_NETWORK": "testnet"
      }
    }
  }
}

Option 2: Local Development Setup (Current)

1. Clone and install:

git clone https://github.com/YOUR_USERNAME/stacks-clarity-mcp.git
cd stacks-clarity-mcp
npm install

2. Build the project:

npm run build

Note: This generates the dist/ folder with compiled JavaScript. The build is required before running the server.

3. Configure Cursor - Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "stacks-clarity-mcp": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/stacks-clarity-mcp/src/server.ts"],
      "env": {
        "HIRO_API_KEY": "",
        "STACKS_NETWORK": "testnet"
      }
    }
  }
}

Important: Replace /absolute/path/to/stacks-clarity-mcp with your actual path!

4. Restart Cursor completely (quit and reopen)

5. Verify Setup:

   • Go to Cursor → Settings → MCP
   • Look for green indicator next to stacks-clarity-mcp
   • Switch to Agent mode in chat
   • Test with: "list available stacks tools"

Network Options

• mainnet - Production Stacks network
• testnet - Test network with free tokens
• devnet - Local development with Clarinet

Get Hiro API Key (Optional)

For enhanced features and higher rate limits:

1. Visit platform.hiro.so
2. Create an account and generate an API key
3. Add to HIRO_API_KEY in your config

📚 Detailed guides: See integration_guides/ folder for Cursor, Claude Code, and Development setup.

📦 What's Included in the Repository

Included (pushed to GitHub):

• ✅ src/ - TypeScript source code (452KB)
• ✅ stacks-clarity-standards/ - All 30+ SIP standards (9.2MB)
• ✅ integration_guides/ - Setup documentation
• ✅ package.json, tsconfig.json - Configuration files

Excluded (not pushed):

• ❌ node_modules/ - Dependencies (165MB) - install with npm install
• ❌ dist/ - Build output (448KB) - generate with npm run build
• ❌ .cursor/ - Local MCP config
• ❌ .env - Environment variables

Setup Requirement: After cloning, you must run npm install and npm run build before using the MCP server.

📖 Available Tools (32 Total)

🔍 Standards & Documentation (5 tools)

• list_sips - Discover all available SIP standards
• get_sip - Get specific SIP content (SIP-009, SIP-010, etc.)
• get_clarity_book - Complete Clarity language reference (34,000+ lines)
• get_token_standards - Essential SIP-009/SIP-010 standards
• search_sips - Search SIPs by topic

🪙 Token Development (8 tools)

SIP-010 Fungible Tokens

• get_sip010_info - Token contract information and metadata
• get_sip010_balance - Check FT balances for addresses
• generate_sip010_transfer - Create transfer transactions with post-conditions
• generate_sip010_template - Generate complete SIP-010 compliant contracts

SIP-009 Non-Fungible Tokens

• get_sip009_token_info - NFT information and metadata
• get_sip009_collection_info - Collection-level information
• generate_sip009_transfer - Create NFT transfers with post-conditions
• generate_sip009_template - Generate complete SIP-009 compliant contracts

🔐 Security & Post-Conditions (5 tools)

• generate_fungible_post_condition - Mandatory FT post-conditions
• generate_nonfungible_post_condition - Mandatory NFT post-conditions
• generate_stx_post_condition - STX transfer post-conditions
• analyze_transaction_post_conditions - Validate transaction security
• generate_post_condition_template - Security templates and patterns

⚡ Performance Optimization - SIP-012 (3 tools)

• analyze_contract_performance - Comprehensive performance analysis
• estimate_operation_cost - Cost estimation for Clarity operations
• generate_optimization_recommendations - SIP-012 optimization strategies

👤 Account Management (4 tools)

• get_stacks_account_info - Comprehensive account information
• check_stx_balance - Simple STX and token balance checks
• get_transaction_history - Account transaction history with pagination
• validate_stacks_address - Address format and network validation

🧪 Development & Testing (4 tools)

• generate_clarinet_project - Complete Clarinet project setup
• generate_clarity_contract - SIP-compliant contract generation
• generate_contract_tests - Unit, integration, and security tests
• configure_clarinet_project - Network and environment configuration

🎨 Frontend Development (3 tools)

• build_clarity_smart_contract - Smart contract development guidance
• build_stacks_frontend - Frontend integration with @stacks/connect
• build_stacks_dapp - Complete full-stack development guide

🚀 Quick Start Guide

1. Explore Available Standards

// Discover all SIP standards
use tool: list_sips

// Get specific token standards
use tool: get_token_standards

// Access complete Clarity reference
use tool: get_clarity_book

2. Build a SIP-010 Token

// Generate compliant token contract
use tool: generate_sip010_template
params: {
  tokenName: "MyToken",
  symbol: "MTK",
  decimals: 6,
  features: ["minting", "burning"]
}

// Create secure transfer
use tool: generate_sip010_transfer
params: {
  contractId: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.my-token",
  amount: 1000000,
  sender: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R",
  recipient: "ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG",
  memo: "Secure transfer with post-conditions"
}

3. Set Up Development Environment

// Initialize Clarinet project
use tool: generate_clarinet_project
params: {
  projectName: "my-stacks-project",
  template: "fungible-token"
}

// Generate comprehensive tests
use tool: generate_contract_tests
params: {
  contractName: "my-token",
  testType: "security",
  scenarios: ["post-conditions", "authorization"]
}

🔒 Security Features

Mandatory Post-Conditions

All token transfers MUST include post-conditions. The MCP server enforces this:

// ✅ CORRECT: Transfer with post-conditions
use tool: generate_fungible_post_condition
params: {
  address: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R",
  contractId: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.token",
  amount: 1000000,
  condition: "equal"
}

// Always use PostConditionMode.Deny for maximum security

SIP Compliance Enforcement

• Automatic SIP-009 and SIP-010 compliance checking
• Native asset function usage (ft-transfer?, nft-transfer?)
• Proper error handling and authorization patterns

⚡ Performance Optimization

SIP-012 Benefits

• 2x Database Operations: Increased read/write limits per block
• Dynamic List Storage: Pay only for actual data size
• Optimized Cost Functions: 100+ improved cost calculations

// Analyze contract performance
use tool: analyze_contract_performance
params: {
  contractCode: "...", // Your Clarity contract
  optimizationLevel: "advanced"
}

// Get optimization recommendations
use tool: generate_optimization_recommendations
params: {
  contractPattern: "token-contract",
  currentIssues: ["high gas costs", "multiple map operations"]
}

📚 Comprehensive Documentation

Access to complete Stacks development resources:

• 34,000+ lines of Clarity Book documentation
• 30+ SIP standards with full implementations
• Security patterns and best practices
• Performance optimization guides
• Frontend integration examples

🏗️ Integration Examples

React Frontend with @stacks/connect

// Get complete frontend guidance
use tool: build_stacks_frontend

// Generate wallet connection code
// Transaction signing with post-conditions
// Error handling and user experience

DeFi Protocol Development

// Performance-optimized DeFi contract
use tool: generate_clarity_contract
params: {
  contractName: "amm-pool",
  contractType: "custom",
  features: ["governance", "staking"]
}

// Security testing
use tool: generate_contract_tests
params: {
  contractName: "amm-pool",
  testType: "security",
  scenarios: ["reentrancy", "authorization", "post-conditions"]
}

NFT Marketplace

// SIP-009 compliant NFT collection
use tool: generate_sip009_template
params: {
  collectionName: "Art Collection",
  symbol: "ART",
  features: ["metadata", "royalties"]
}

// Marketplace contract with escrow
use tool: generate_clarity_contract
params: {
  contractName: "nft-marketplace",
  contractType: "custom",
  features: ["escrow", "royalties"]
}

🔧 Development Workflow

1. Research Standards: Use list_sips and get_sip to understand requirements
2. Generate Contracts: Use template tools for SIP-compliant implementations
3. Security Testing: Generate comprehensive security test suites
4. Performance Optimization: Analyze and optimize using SIP-012 tools
5. Frontend Integration: Build user interfaces with wallet connectivity
6. Deployment: Use Clarinet tools for production deployment

📋 Production Checklist

• ✅ SIP compliance validated
• ✅ Mandatory post-conditions implemented
• ✅ Security tests passing
• ✅ Performance optimized with SIP-012
• ✅ Frontend properly integrated
• ✅ All tests (unit, integration, security) passing

🐛 Troubleshooting

MCP Server Not Appearing in Cursor

1. Check MCP Settings:

   • Go to Cursor → Settings → Cursor Settings → MCP
   • Look for stacks-clarity-mcp entry
   • Check if indicator is green (connected) or red (error)
   • Click on the entry to see error details

2. Verify Configuration:

   • Ensure .cursor/mcp.json exists in project root
   • For local development, use absolute path to server.ts
   • Check that Node.js is installed: node --version

3. Restart Cursor:

   • Completely quit Cursor (not just close window)
   • Reopen Cursor
   • Wait 10-15 seconds for MCP to initialize

4. Check Agent Mode:

   • In Cursor chat, ensure dropdown is set to Agent (not normal chat)
   • MCP tools only work in Agent mode

5. Test MCP Connection:

   # Test the server directly
   npx tsx /path/to/server.ts
   
   # Or use MCP Inspector
   npx @modelcontextprotocol/inspector
   

Common Issues

"Command not found": Make sure you're using npx tsx not just tsx

"Module not found": Run npm install in the MCP server directory

Build errors: For local development, use tsx to run from source (skips build step)

Tools not visible: Ensure you're in Agent mode and the MCP shows green indicator

Getting Help

• Check integration guides for detailed setup
• Review development_usage.md for local development
• Use MCP Inspector to test tools: npx @modelcontextprotocol/inspector

🤝 Contributing

This MCP server implements the complete Stacks development stack. Contributions should maintain:

• Security-first principles
• SIP standard compliance
• Performance optimization focus
• Comprehensive documentation

📄 License

This project is licensed under the Apache-2.0 License.

🔗 Resources

• Stacks Documentation
• Clarity Language Reference
• SIP Standards
• Clarinet CLI
• Stacks.js

---

Built for professional Stacks development with security, performance, and compliance as top priorities.