🔐 SCRT Network MCP Server v0.1

Production-ready Model Context Protocol (MCP) server for Secret Network blockchain integration

Features • Quick Start • Tools • Examples • Prompts • Security

🚀 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

Tool	Description	Parameters	Returns
`get_blockchain_info`	Get current blockchain information	None	Height, chain ID, latest block
`get_node_info`	Get node sync status and info	None	Node details, sync status
`get_network_parameters`	Get network parameters	None	Staking, slashing, governance params

🏆 Validator Tools

Tool	Description	Parameters	Returns
`get_validators`	Get list of validators	`status`	Validators with `validatorURL`

💰 Account Tools

Tool	Description	Parameters	Returns
`get_account_balance`	Get account balance	`address` (optional)	Balance with `accountExplorerURL`
`get_staking_info`	Get staking details	`address` (optional)	Delegations, unbonding, rewards

📝 Transaction Tools

Tool	Description	Parameters	Returns
`get_transaction`	Get transaction by hash	`hash`	Transaction with `explorerURL`
`get_transactions_by_address`	Get address transactions	`address` (optional), `limit`	Transaction history
`send_tokens`	Send tokens	`to_address`, `amount`, `denom`, `from_address`, `private_key`	Transaction hash
`ibc_transfer`	IBC cross-chain transfer	`to_address`, `amount`, `source_channel`, etc.	Transaction hash

🏛️ Governance Tools

Tool	Description	Parameters	Returns
`get_governance_proposals`	Get proposals	`status`	Proposals with `proposalURL`

📜 Smart Contract Tools

Tool	Description	Parameters	Returns
`search_contracts`	Search by code ID	`code_id`	Contracts with `contractExplorerURL`
`get_contract_info`	Get contract details	`address`	Contract info
`query_smart_contract`	Query contract	`address`, `query`	Query result
`execute_contract`	Execute contract	`contract_address`, `msg`, `sender_address`, `private_key`	Transaction hash
`migrate_contract`	Migrate contract	`contract_address`, `new_code_id`, `msg`	Transaction hash

💸 Advanced Transaction Tools

Tool	Description	Parameters	Returns
`grant_fee_allowance`	Grant fee payment permission	`grantee_address`, `spend_limit`	Transaction hash
`revoke_fee_allowance`	Revoke fee permission	`grantee_address`	Transaction hash
`create_vesting_account`	Create vesting account	`to_address`, `amount`, `end_time`	Transaction hash
`create_multisig_tx`	Create multi-sig transaction	`multisig_address`, `signers`, `threshold`, `msg`	Unsigned transaction

ℹ️ Utility Tools

Tool	Description	Parameters	Returns
`generate_wallet`	Generate new Secret Network wallet	None	Address, mnemonic, private key
`get_wallet_info`	Get configured wallet info	None	Wallet configuration status

💡 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

Endpoint Type	Rate Limit	Notes
LCD API	100 req/sec	Public endpoint
RPC API	50 req/sec	Public endpoint
Contract Queries	50 req/sec	Encrypted queries

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

📝 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

Built by Tairon.ai team with help from Claude

FilesExpand file tree

README.md

Latest commit

History