Osmosis MCP Server

Osmosis MCP Server

A comprehensive MCP (Model Context Protocol) server for interacting with the Osmosis blockchain. This server provides AI assistants with 158 tools covering every aspect of the Osmosis ecosystem, from basic blockchain queries to advanced DeFi operations, smart contract interactions, wallet management, direct transaction execution, and testnet utilities.

Features

Core Blockchain Operations

• Query blockchain status, blocks, and transactions
• Get account balances and token information
• Retrieve chain parameters and module accounts
• Monitor epochs and network state

Liquidity Pools & Trading

• Query all pool types (Balancer, Stableswap, Concentrated Liquidity)
• Get pool information, liquidity, fees, and APR
• Estimate swaps and prepare trading transactions
• Access historical price data and trading records

Concentrated Liquidity (CL)

• Manage CL positions and liquidity ranges
• Convert between prices and ticks
• Query pool incentives and fee growth
• Prepare position creation and management transactions

Staking & Governance

• Query validators, delegations, and rewards
• Prepare staking, unstaking, and redelegation transactions
• Access governance proposals, votes, and tallies
• Get staking parameters and commission rates

DeFi & Advanced Features

• Time-Weighted Average Price (TWAP) calculations
• Token lockups and superfluid staking
• IBC denomination tracing
• MEV/arbitrage tracking via ProtoRev

Smart Contracts (CosmWasm)

• Query and execute smart contracts
• Get contract information and history
• Prepare contract instantiation and migration
• Estimate gas fees for contract operations

Token Factory

• Create custom tokens with metadata
• Mint and burn token factory denominations
• Manage token administration and parameters

Specialized Features

• Downtime detection and validator preferences
• IBC rate limiting and fee token management

🚀 NEW: Direct Transaction Execution (37 Tools)

• Bank Operations: Send tokens, multi-send transactions
• Governance: Submit proposals, vote, deposit on proposals
• Lockup & Incentives: Lock tokens, claim rewards, create gauges
• IBC Transfers: Cross-chain token transfers
• Superfluid Staking: Liquid staking with LP tokens
• Pool Operations: Create pools, advanced swaps
• Token Factory: Create custom tokens, mint/burn
• Module Administration: Parameter updates, upgrades

🔐 Wallet Management (6 Tools)

• Generate new Osmosis wallets with BIP-39 mnemonics
• Restore wallets from seed phrases
• Validate addresses and mnemonics
• Derive addresses from public keys

🧪 NEW: Testnet Utilities (3 Tools)

• Check Network Status: Verify if on testnet/mainnet with safety warnings
• Get Testnet Tokens: Complete guide to faucets and token sources
• Testnet Faucet: Direct integration with Osmosis testnet faucet
• Pool incentives and superfluid parameters

Installation

Usage

Running the Server

Configuring in Claude Desktop

1. Open Claude Desktop
2. Go to Settings
3. Navigate to the MCP section
4. Add a new server with the following configuration:
   • Name: Osmosis Blockchain Server
   • Command: path/to/osmosis-mcp-server/build/index.js

Available Tools

The server exposes 158 tools organized into 12 categories:

📊 Blockchain Tools (9 tools)

• get-blockchain-status - Get current blockchain status
• get-account-balance - Get token balances for an address
• get-epochs - Get epoch information
• get-transaction - Get transaction details by hash
• get-latest-blocks - Get recent block information
• get-token-info - Get token metadata
• get-supply - Get token supply information
• get-chain-params - Get chain parameters
• get-module-accounts - Get module account information

🏊 Pool Tools (18 tools)

• get-pool-info - Get pool information
• get-all-pools - Get all liquidity pools
• get-pool-spot-price - Get current spot price
• estimate-swap - Estimate swap results
• get-incentivized-pools - Get pools with incentives
• get-pool-incentives - Get pool incentive information
• get-pool-type - Get pool type (balancer/stableswap/CL)
• get-historical-prices - Get historical price data
• prepare-swap-transaction - Prepare swap transaction
• get-pool-total-shares - Get total LP shares
• get-pool-liquidity - Get pool liquidity details
• get-pool-swap-fee - Get pool swap fees
• get-pool-exit-fee - Get pool exit fees
• get-pool-join-exit-records - Get join/exit history
• get-pool-total-value-locked - Get pool TVL
• prepare-join-pool - Prepare join pool transaction
• prepare-exit-pool - Prepare exit pool transaction
• get-pool-apr - Get pool APR

🎯 Concentrated Liquidity Tools (15 tools)

• get-cl-pools - Get all CL pools
• get-cl-positions - Get CL positions for address
• get-cl-position - Get specific CL position details
• get-cl-positions-by-pool - Get all positions in a pool
• get-cl-user-positions - Get user's CL positions
• price-to-tick - Convert price to tick
• tick-to-price - Convert tick to price
• get-cl-pool-incentives - Get CL pool incentives
• get-cl-pool-liquidity - Get CL pool liquidity
• get-cl-pool-tick-data - Get tick spacing and current tick
• get-cl-pool-fee-growth - Get fee growth statistics
• prepare-cl-create-position - Prepare create position transaction
• prepare-cl-add-liquidity - Prepare add liquidity transaction
• prepare-cl-remove-liquidity - Prepare remove liquidity transaction
• get-cl-swap-estimates - Get CL-specific swap estimates

🥩 Staking Tools (15 tools)

• get-validators - Get validator information
• get-delegations - Get delegations for address
• get-staking-rewards - Get pending staking rewards
• get-unbonding-delegations - Get unbonding delegations
• get-validator-delegations - Get all delegations to validator
• get-validator-unbonding-delegations - Get validator unbonding delegations
• get-validator-commission - Get validator commission
• get-validator-self-delegation - Get validator self-delegation
• prepare-delegate - Prepare delegation transaction
• prepare-undelegate - Prepare undelegation transaction
• prepare-redelegate - Prepare redelegation transaction
• prepare-claim-rewards - Prepare claim rewards transaction
• get-staking-params - Get staking parameters
• get-slashing-params - Get slashing parameters
• get-distribution-params - Get distribution parameters

🗳️ Governance Tools (4 tools)

• get-proposals - Get governance proposals
• get-proposal-details - Get proposal details
• get-proposal-votes - Get proposal votes
• get-proposal-tally - Get proposal vote tally

💰 DeFi Tools (5 tools)

• get-twap - Get Time-Weighted Average Price
• get-lockups - Get token lockup information
• get-superfluid-assets - Get superfluid staking assets
• get-denoms-by-creator - Get token factory denoms by creator
• get-ibc-denom-trace - Get IBC token source information

📜 CosmWasm Tools (20 tools)

• get-wasm-codes - Get all uploaded WASM codes
• get-wasm-code-info - Get WASM code information
• get-contracts-by-code - Get contracts by code ID
• get-contract-info - Get contract metadata
• query-contract-state - Query contract state
• get-contract-history - Get contract migration history
• prepare-instantiate-contract - Prepare contract instantiation
• prepare-execute-contract - Prepare contract execution
• prepare-migrate-contract - Prepare contract migration
• get-contract-code-id - Get contract code ID
• get-contract-admin - Get contract admin
• get-contract-label - Get contract label
• query-contract-raw - Query raw contract storage
• get-pinned-codes - Get pinned code IDs
• get-code-metadata - Get code metadata
• validate-contract-address - Validate contract address
• estimate-instantiate-fee - Estimate instantiation gas
• estimate-execute-fee - Estimate execution gas
• get-contract-ibc-port - Get contract IBC port
• get-contract-events - Get contract events

🏭 Token Factory Tools (10 tools)

• get-token-factory-denoms - Get all token factory denoms
• get-token-factory-denom-info - Get token factory denom metadata
• get-token-factory-creator - Get token creator address
• prepare-create-token-factory-denom - Prepare create token transaction
• prepare-mint-token-factory-tokens - Prepare mint tokens transaction
• prepare-burn-token-factory-tokens - Prepare burn tokens transaction
• prepare-change-token-factory-admin - Prepare change admin transaction
• get-token-factory-params - Get token factory parameters
• validate-token-factory-denom - Validate token factory denom
• get-token-factory-total-supply - Get token total supply

⚡ ProtoRev Tools (8 tools)

• get-protorev-profits-by-denom - Get MEV profits by denomination
• get-protorev-profits-by-tx - Get MEV profits by transaction
• get-protorev-statistics - Get overall MEV statistics
• get-protorev-number-of-trades - Get ProtoRev trade count
• get-protorev-enabled - Check if ProtoRev is enabled
• get-protorev-developer-account - Get developer account
• get-protorev-max-pool-points - Get max pool points per tx
• get-protorev-pool-weights - Get pool weight configuration

🔧 Specialized Tools (11 tools)

• get-downtime-detector-params - Get downtime detector parameters
• get-downtime-status - Get current downtime status
• get-validator-set-preference - Get validator set preferences
• get-ibc-rate-limits - Get IBC rate limiting info
• get-mint-params - Get token minting parameters
• get-epoch-provisions - Get current epoch provisions
• get-all-locks-by-type - Get locks by type
• get-synthetic-locks-by-lock-id - Get synthetic lock details
• get-fee-tokens - Get accepted fee tokens
• get-pool-incentives-params - Get pool incentives parameters
• get-superfluid-params - Get superfluid parameters

🔐 Wallet Management Tools (6 tools)

• generate-wallet - Generate new Osmosis wallet with mnemonic
• restore-wallet-from-mnemonic - Restore wallet from seed phrase
• get-wallet-address - Get address from mnemonic
• validate-mnemonic - Validate BIP-39 mnemonic phrase
• validate-address - Validate Osmosis address format
• derive-address-from-pubkey - Derive address from public key

🚀 Execution Tools (37 tools) - NEW!

Bank Operations (3 tools)

• send - Send tokens to another address
• multi-send - Send tokens to multiple addresses
• set-send-enabled - Enable/disable sending for token types

Governance Operations (4 tools)

• submit-proposal - Submit governance proposal
• vote-proposal - Vote on governance proposal
• deposit-proposal - Deposit tokens to proposal
• claim-community-pool - Claim community pool rewards

Lockup & Incentive Operations (6 tools)

• lock-tokens - Lock tokens for incentive rewards
• begin-unlocking - Start unlocking specific locked tokens
• begin-unlocking-all - Start unlocking all locked tokens
• unlock-period-lock - Unlock completed period locks
• claim-incentives - Claim available incentive rewards
• create-gauge - Create new incentive gauge

IBC Operations (4 tools)

• ibc-transfer - Transfer tokens across chains
• timeout-packet - Handle IBC packet timeouts
• acknowledge-packet - Acknowledge IBC packets
• update-client - Update IBC light clients

Advanced Pool Operations (8 tools)

• create-pool - Create new liquidity pools
• join-swap-extern-amount-in - Advanced join-swap operations
• join-swap-share-amount-out - Join-swap with share output
• exit-swap-extern-amount-out - Advanced exit-swap operations
• exit-swap-share-amount-in - Exit-swap with share input
• create-cosmwasm-pool - Create CosmWasm-based pools
• stable-swap - Perform stable asset swaps
• set-pool-weights - Adjust pool weights

Superfluid Staking Operations (4 tools)

• superfluid-delegate - Delegate LP tokens via Superfluid
• superfluid-undelegate - Undelegate Superfluid tokens
• lock-and-superfluid-delegate - Lock and delegate in one tx
• unlock-and-migrate-superfluid-tokens - Unlock and migrate

Token Factory Advanced Operations (3 tools)

• set-token-metadata - Set custom token metadata
• force-transfer - Admin force transfer tokens
• set-before-send-hook - Set token transfer hooks

Module Administration (5 tools)

• update-params - Update module parameters
• upgrade-proposal - Submit software upgrade proposal
• cancel-upgrade - Cancel pending upgrade
• set-withdrawal-address - Set reward withdrawal address
• fund-community-pool - Fund community pool

Example Interactions

Basic Blockchain Queries

Ask Claude:

Pool and Trading Operations

Concentrated Liquidity Management

Staking and Governance

Smart Contract Interactions

Token Factory Operations

Advanced Analytics

🚀 NEW: Direct Transaction Execution

Security Notes

⚠️ UPDATED SECURITY MODEL:

• Default Network: TESTNET (for safety during execution tools testing)
• Execution Tools: Can sign and broadcast transactions directly using provided mnemonics
• Query Tools: Read-only operations, no private key handling
• Production Use: Set OSMOSIS_NETWORK=mainnet environment variable for mainnet
• Mnemonic Handling: Mnemonics are processed in-memory only, never stored
• Testnet First: Always test with testnet before using mainnet funds

Development

Tool Categories Summary

Architecture

The server is built with:

• TypeScript for type safety
• @modelcontextprotocol/sdk for MCP protocol implementation
• @cosmjs/stargate for Cosmos SDK interactions
• osmojs for Osmosis-specific operations
• axios for HTTP API calls
• zod for input validation

Each tool category is modular and can be used independently, making the server highly maintainable and extensible.

License

MIT