Tairon-ai/scrt-network-mcp

🚀 Features

🔐 Secret Network Integration

• Full Secret Network API integration with LCD and RPC endpoints
• Privacy-preserving smart contract interactions with encrypted inputs/outputs
• IBC (Inter-Blockchain Communication) support for cross-chain transfers
• Real-time blockchain data access and monitoring
• Validator information and staking operations
• Governance proposal tracking and voting
• Dual operation modes - read-only without keys, full transaction signing with wallet configuration

🔗 Direct Links Integration

• Every response includes relevant explorer URLs
• Transactions include explorerURL to Secret Network explorers
• Accounts provide accountExplorerURL
• Validators include validatorURL
• Smart contracts link to contractExplorerURL
• Proposals show proposalURL
• No extra API calls needed - links are generated automatically

📊 Blockchain Operations

• Query blockchain info, height, and node status
• Network parameters (staking, slashing, governance, mint)
• Real-time validator tracking and status
• Account balance queries with automatic wallet detection
• Transaction history and detailed transaction lookups
• Staking delegations, unbonding, and rewards tracking

💎 Transaction Capabilities

• Send tokens with optional wallet configuration
• IBC transfers between blockchains
• Fee grant management (allow others to pay your fees)
• Vesting account creation with locked tokens
• Smart contract execution with encrypted messages
• Contract migration for administrators
• Multi-signature transaction creation

👛 Wallet Management

• Environment-based default wallet configuration
• Support for mnemonic phrase or private key
• User-provided wallet override capability
• Automatic wallet validation and fallback
• Secure key management practices
• Multi-wallet transaction support

📈 Smart Contract Features

• Query smart contracts with encrypted inputs
• Execute contracts with SecretJS encryption
• Contract info and code retrieval
• Contract search by code ID
• Contract migration support
• Privacy-preserving computations

🏛️ Enterprise-Ready Architecture

• Built with SecretJS SDK and Express.js
• Comprehensive error handling with fallback mechanisms
• Docker containerization support
• Production-tested components
• MCP protocol implementation
• 20+ specialized tools for blockchain operations
• Zero-configuration deployment for read operations

📦 Quick Start

Note: This MCP server provides full read-only access to Secret Network data without requiring wallet configuration. Private keys are only needed for transaction signing.

✅ Prerequisites

# Required
Node.js >= 18.0.0
npm >= 9.0.0

🔑 Wallet Configuration

Important: Wallet configuration is optional for read operations.

• Without Wallet: All query operations work (blockchain info, balances, validators, etc.)
• With Wallet: Enable transaction signing (send tokens, IBC transfers, contract execution)
• Configuration: Set in environment variables (see .env.example)

📥 Installation

# Clone the repository
git clone https://github.com/Tairon-ai/scrt-network-mcp.git
cd scrt-network-mcp/mcp-server

# Install dependencies
npm install

# Configure environment (optional for transactions)
cp .env.example .env
# Edit .env only if you want transaction capabilities

# Start the server
npm start

# Development mode
npm run dev

# MCP stdio server for Claude Desktop
npm run mcp

🤖 Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "scrt-network": {
      "command": "node",
      "args": ["/path/to/scrt-network-mcp/mcp-server/mcp/index.js"],
      "env": {
        "SCRT_LCD_ENDPOINT": "https://lcd.mainnet.secretsaturn.net",
        "SCRT_RPC_ENDPOINT": "https://rpc.mainnet.secretsaturn.net",
        "SCRT_WALLET_ADDRESS": "",  // Optional: Your Secret address
        "SCRT_WALLET_MNEMONIC": ""  // Optional: Your mnemonic phrase
      }
    }
  }
}

🛠 Available Tools

📊 Blockchain Tools

🏆 Validator Tools

💰 Account Tools

📝 Transaction Tools

🏛️ Governance Tools

📜 Smart Contract Tools

💸 Advanced Transaction Tools

ℹ️ Utility Tools

💡 Examples

🔐 Get Blockchain Info

// Request
{
  "tool": "get_blockchain_info",
  "params": {}
}

// Response includes
{
  "chainId": "secret-4",
  "height": "12345678",
  "latestBlock": {
    "hash": "0x...",
    "time": "2024-01-01T00:00:00Z"
  }
}

🔑 Generate New Wallet

{
  "tool": "generate_wallet",
  "params": {}
}

// Response includes
{
  "address": "secret1abc...",
  "mnemonic": "word1 word2 ... word24",
  "privateKey": "hex_private_key",
  "publicKey": "hex_public_key",
  "warning": "IMPORTANT: Save these credentials securely!"
}

💰 Check Balance

{
  "tool": "get_account_balance",
  "params": {
    "address": "secret1..." // Optional if wallet configured
  }
}

📤 Send Tokens

{
  "tool": "send_tokens",
  "params": {
    "to_address": "secret1abc...",
    "amount": "1000000",  // 1 SCRT in uscrt
    "denom": "uscrt",
    "memo": "Payment"
  }
}

🌉 IBC Transfer

{
  "tool": "ibc_transfer",
  "params": {
    "to_address": "cosmos1...",
    "amount": "1000000",
    "source_channel": "channel-0",
    "denom": "uscrt"
  }
}

📜 Query Smart Contract

{
  "tool": "query_smart_contract",
  "params": {
    "address": "secret1contract...",
    "query": {
      "balance": {
        "address": "secret1user..."
      }
    }
  }
}

🏛️ Get Proposals

{
  "tool": "get_governance_proposals",
  "params": {
    "status": "PROPOSAL_STATUS_VOTING_PERIOD"
  }
}

💎 Execute Contract

{
  "tool": "execute_contract",
  "params": {
    "contract_address": "secret1contract...",
    "msg": {
      "transfer": {
        "recipient": "secret1...",
        "amount": "1000000"
      }
    }
  }
}

🔑 Grant Fee Allowance

{
  "tool": "grant_fee_allowance",
  "params": {
    "grantee_address": "secret1...",
    "spend_limit": "1000000"  // 1 SCRT limit
  }
}

🤖 Prompts

💬 Example Prompts for AI Assistants

🌍 Blockchain Queries

"What's the current height of Secret Network?"
"Show me the latest block information"
"Get Secret Network node sync status"
"What are the network staking parameters?"
"Show me the slashing parameters"
"Get governance voting parameters"
"What's the current inflation rate?"
"Show network mint parameters"
"Get distribution parameters"
"What chain ID is Secret Network using?"

🏆 Validator Information

"Show me all active validators on Secret Network"
"Get unbonding validators"
"Find unbonded validators"
"Show validator details for secret1valoper..."
"Get top validators by voting power"
"Show validator commission rates"
"Find validators with low commission"
"Get validator uptime information"
"Show jailed validators"
"Find validators accepting delegations"

💰 Account & Balance Queries

"Check my SCRT balance"
"Get balance for secret1abc..."
"Show all balances for my wallet"
"Check account balance in SCRT"
"Get token balances for address"
"Show my available balance"
"Check staking rewards"
"Get unbonding amounts"
"Show total portfolio value"
"Check vesting account balance"

📤 Token Transfers

"Send 10 SCRT to secret1abc..."
"Transfer 100 SCRT to this address"
"Send tokens with memo 'Payment'"
"Transfer 0.5 SCRT to my friend"
"Send maximum amount to secret1..."
"Transfer tokens from my wallet"
"Send SCRT with custom fee"
"Transfer tokens with high priority"
"Send all my SCRT to..."
"Make a payment of 50 SCRT"

🌉 IBC Transfers

"Transfer SCRT to Cosmos Hub via IBC"
"Send tokens to Osmosis through channel-1"
"IBC transfer to Juno Network"
"Bridge SCRT to Terra"
"Send tokens cross-chain to Akash"
"Transfer to cosmos1... via IBC"
"Bridge 100 SCRT to Osmosis"
"Send tokens to another blockchain"
"IBC transfer with timeout"
"Cross-chain transfer to Stride"

📝 Transaction History

"Get my recent transactions"
"Show transaction hash ABC123..."
"Find transactions for my wallet"
"Get last 50 transactions"
"Show transactions from today"
"Find failed transactions"
"Get successful transfers"
"Show IBC transactions"
"Find transactions with memo"
"Get transaction details for..."

🥩 Staking Operations

"Show my staking delegations"
"Get unbonding delegations"
"Check staking rewards"
"Show delegation to validator X"
"Get total staked amount"
"Check rewards from all validators"
"Show pending rewards"
"Get staking APR"
"Find best validators to stake with"
"Show my staking portfolio"

🏛️ Governance

"Show active governance proposals"
"Get proposals in voting period"
"Show passed proposals"
"Get rejected proposals"
"Find proposals in deposit period"
"Show proposal #123 details"
"Get governance proposal history"
"Find proposals about staking"
"Show community pool proposals"
"Get software upgrade proposals"

📜 Smart Contracts

"Query secret contract at address..."
"Get contract info for secret1..."
"Search contracts with code ID 123"
"Execute transfer on contract"
"Query token balance on contract"
"Get contract code hash"
"Find all contracts by code ID"
"Execute swap on DEX contract"
"Query liquidity pool info"
"Migrate contract to new code"

💸 Fee Management

"Grant fee allowance to secret1..."
"Allow address X to pay my fees"
"Revoke fee grant for address"
"Set 10 SCRT fee allowance"
"Create fee grant with expiry"
"Show my fee grants"
"Check who can pay my fees"
"Remove fee allowance"
"Grant unlimited fee allowance"
"Set daily fee limit"

🔐 Vesting Accounts

"Create vesting account for employee"
"Set up 1 year vesting schedule"
"Create delayed vesting account"
"Lock 1000 SCRT until next year"
"Create vesting with cliff period"
"Set up token vesting plan"
"Create continuous vesting"
"Lock tokens for 6 months"
"Create vesting for team member"
"Set up investor vesting"

🔑 Wallet Management

"Generate new Secret Network wallet"
"Create new wallet with mnemonic"
"Generate wallet for testing"
"Create fresh wallet address"
"Get new wallet credentials"
"Generate wallet for user"
"Create wallet with private key"
"Make new Secret account"
"Generate secure wallet"
"Create wallet for staking"

🔐 Multi-signature

"Create multisig transaction"
"Set up 2-of-3 multisig"
"Create transaction for signing"
"Generate multisig address"
"Create unsigned transaction"
"Set threshold for multisig"
"Add signers to multisig"
"Create complex multisig tx"
"Set up corporate multisig"
"Create multisig with 5 signers"

🔍 Advanced Queries

"Show wallet configuration status"
"Get default wallet address"
"Check if wallet is configured"
"Show available signing capabilities"
"Get chain configuration"
"Check LCD endpoint status"
"Show RPC connection info"
"Get network chain ID"
"Check wallet signing ability"
"Show environment configuration"

💡 Privacy Features

"Execute private computation"
"Query encrypted contract state"
"Send private transaction"
"Execute secret contract function"
"Query private data"
"Interact with privacy token"
"Execute confidential swap"
"Query encrypted balance"
"Send private message"
"Execute sealed bid auction"

📊 Analytics

"Calculate total value locked"
"Show network statistics"
"Get transaction volume today"
"Show active addresses count"
"Calculate staking ratio"
"Get network participation rate"
"Show IBC volume statistics"
"Calculate average block time"
"Get validator performance metrics"
"Show network growth metrics"

🛠️ Development

"Deploy smart contract"
"Query contract admin"
"Update contract code"
"Set contract metadata"
"Get contract source code"
"Verify contract code"
"Instantiate contract"
"Query contract schema"
"Get contract permissions"
"Check contract migration history"

🌐 Network Operations

"Check mainnet status"
"Get testnet information"
"Show network peers"
"Get consensus state"
"Check network latency"
"Show connected nodes"
"Get network topology"
"Check sync progress"
"Show mempool status"
"Get pending transactions"

🔒 Security

🛡️ Security Features

• Private Key Protection - Keys stored securely in environment variables
• Mnemonic Support - BIP39 mnemonic phrase support
• Input Validation - All inputs validated before processing
• Error Handling - Comprehensive error management
• Address Validation - Secret Network address format validation
• HTTPS Only - All API calls use secure connections
• Encrypted Contracts - Native support for Secret Network's encrypted computation

🔐 Best Practices

• Key Management: Never commit private keys or mnemonics
• Wallet Security: Use hardware wallets for production
• Transaction Verification: Always verify transaction details
• Contract Interaction: Validate contract addresses
• Fee Monitoring: Monitor transaction fees
• Network Selection: Ensure correct network (mainnet/testnet)

📊 Supported Infrastructure

🌐 Network Endpoints

• LCD API: https://lcd.mainnet.secretsaturn.net - REST API for queries
• RPC API: https://rpc.mainnet.secretsaturn.net - Tendermint RPC
• Chain ID: secret-4 (mainnet)
• Token: SCRT (uscrt for micro-units)

📊 API Endpoints

• Main LCD: https://lcd.mainnet.secretsaturn.net
• Alternative LCD: https://secretnetwork-api.lavenderfive.com
• RPC Endpoint: https://rpc.mainnet.secretsaturn.net

⚡ Rate Limits

🚀 Deployment

🏭 Production Deployment

# Start production server
NODE_ENV=production npm start

# With PM2
pm2 start mcp/index.js --name scrt-network-mcp

# With Docker
docker build -t scrt-network-mcp .
docker run -d -p 8080:8080 --env-file .env scrt-network-mcp

🔑 Environment Variables

# Server Configuration
PORT=8080

# Secret Network endpoints
SCRT_LCD_ENDPOINT=https://lcd.mainnet.secretsaturn.net
SCRT_RPC_ENDPOINT=https://rpc.mainnet.secretsaturn.net
SCRT_NETWORK=mainnet
SCRT_CHAIN_ID=secret-4

# Wallet Configuration (optional for transactions)
SCRT_WALLET_ADDRESS=secret1...
SCRT_WALLET_MNEMONIC="your twelve word mnemonic phrase..."
# OR use private key instead
# SCRT_WALLET_PRIVATE_KEY=your_private_key_here

# Optional
REQUEST_TIMEOUT=30000
DEBUG=false

📈 Performance

• Response Time: <100ms for local queries
• Transaction Speed: 6-7 second block time
• Query Caching: Intelligent caching for repeated queries
• Concurrent Requests: Optimized for parallel operations
• Error Recovery: Automatic retry with exponential backoff
• Encryption Overhead: Minimal (<50ms) for contract encryption

🎯 Key Features

✨ Privacy-First Design

• Encrypted smart contract state
• Private computation capabilities
• Confidential transactions
• Secure multi-party computation

🔄 Cross-Chain Support

• IBC protocol integration
• Multi-chain asset transfers
• Bridge compatibility
• Interchain accounts

🛤️ Developer Friendly

• Comprehensive toolset
• SecretJS SDK integration
• Clear error messages
• Extensive documentation

🤝 Contributing

We welcome contributions!

# Fork the repository on GitHub, then clone
git clone https://github.com/Tairon-ai/scrt-network-mcp

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
npm test

# Commit and push
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature

# Open Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Secret Network - Privacy-preserving smart contracts
• SecretJS - Secret Network JavaScript SDK
• Model Context Protocol - AI integration standard
• Express.js - Web framework for Node.js

📚 Resources

• Secret Network Docs
• SecretJS Documentation
• Secret Network GitHub
• IBC Protocol
• Cosmos SDK
• Secret Network Explorer

📝 API Access Information

Public Access (Default)

All query tools work without authentication:

• ✅ Full read access to blockchain data
• ✅ Account balances and staking info
• ✅ Validator information and status
• ✅ Transaction history and details
• ✅ Smart contract queries
• ✅ Governance proposals

Authenticated Access (With Wallet)

With wallet configuration, additionally enables:

• ✨ Token transfers and payments
• ✨ IBC cross-chain transfers
• ✨ Smart contract execution
• ✨ Fee grant management
• ✨ Vesting account creation
• ✨ Multi-signature transactions
• ✨ Contract migration