Stacks Clarity MCP

🚀 Stacks Clarity MCP Server (Unofficial)

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.

another one brought to you by

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

🚀 Quick Start

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 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.

💻 Usage Examples

🔍 Standards & Documentation (5 tools)

// Discover all available SIP standards
use tool: list_sips

// Get specific SIP content (SIP-009, SIP-010, etc.)
use tool: get_sip

// Get complete Clarity language reference (34,000+ lines)
use tool: get_clarity_book

// Get essential SIP-009/SIP-010 standards
use tool: get_token_standards

// Search SIPs by topic
use tool: search_sips

🪙 Token Development (8 tools)

SIP-010 Fungible Tokens

// Get token contract information and metadata
use tool: get_sip010_info

// Check FT balances for addresses
use tool: get_sip010_balance

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

// Generate complete SIP-010 compliant contracts
use tool: generate_sip010_template
params: {
  tokenName: "MyToken",
  symbol: "MTK",
  decimals: 6,
  features: ["minting", "burning"]
}

SIP-009 Non-Fungible Tokens

// Get NFT information and metadata
use tool: get_sip009_token_info

// Get collection-level information
use tool: get_sip009_collection_info

// Create NFT transfers with post-conditions
use tool: generate_sip009_transfer

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

🔐 Security & Post-Conditions (5 tools)

// Generate mandatory FT post-conditions
use tool: generate_fungible_post_condition

// Generate mandatory NFT post-conditions
use tool: generate_nonfungible_post_condition

// Generate STX transfer post-conditions
use tool: generate_stx_post_condition

// Validate transaction security
use tool: analyze_transaction_post_conditions

// Generate security templates and patterns
use tool: generate_post_condition_template

⚡ Performance Optimization - SIP-012 (3 tools)

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

// Estimate cost for Clarity operations
use tool: estimate_operation_cost

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

👤 Account Management (4 tools)

// Get comprehensive account information
use tool: get_stacks_account_info

// Check STX and token balances
use tool: check_stx_balance

// Get account transaction history with pagination
use tool: get_transaction_history

// Validate address format and network
use tool: validate_stacks_address

🧪 Development & Testing (4 tools)

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

// Generate SIP-compliant contract
use tool: generate_clarity_contract

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

// Configure network and environment
use tool: configure_clarinet_project

🎨 Frontend Development (3 tools)

// Get smart contract development guidance
use tool: build_clarity_smart_contract

// Get frontend integration with @stacks/connect
use tool: build_stacks_frontend

// Get complete full-stack development guide
use tool: build_stacks_dapp

🚀 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"]
}

🔧 Technical Details

🔒 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"]
}

📚 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.