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.

🚀 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)

Clone and install:

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

Build the project:

npm run build

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

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!

Restart Cursor completely (quit and reopen)
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:

Visit platform.hiro.so
Create an account and generate an API key
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

Research Standards: Use list_sips and get_sip to understand requirements
Generate Contracts: Use template tools for SIP-compliant implementations
Security Testing: Generate comprehensive security test suites
Performance Optimization: Analyze and optimize using SIP-012 tools
Frontend Integration: Build user interfaces with wallet connectivity
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

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
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
Restart Cursor:
- Completely quit Cursor (not just close window)
- Reopen Cursor
- Wait 10-15 seconds for MCP to initialize
Check Agent Mode:
- In Cursor chat, ensure dropdown is set to Agent (not normal chat)
- MCP tools only work in Agent mode
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

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