Keplr Wallet MCP

[!WARNING] Beta Notice: Keplr Wallet MCP is in beta and may contain bugs or unexpected behavior. By using this software, you acknowledge that you do so at your own risk. The developers are not liable for any loss of funds or damages arising from the use of this software.

Your AI-powered wallet for Cosmos. Send, stake, swap — just ask. Currently supporting 40+ chains via the Model Context Protocol.

Installation

npm install @keplr-wallet/keplr-wallet-mcp

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "keplr": {
      "command": "npx",
      "args": ["@keplr-wallet/keplr-wallet-mcp"]
    }
  }
}

Claude Code

claude mcp add keplr -- npx @keplr-wallet/keplr-wallet-mcp

Advanced Configuration

For plugin registration, RPC overrides, or toolset filtering, create a keplr-mcp.config.ts in your working directory. See the Environment Variables for details.

Tool Discovery

Use the meta-tools for efficient tool discovery:

1. search-tools(query: "send cosmos") → Find relevant tools
2. describe-tools(names: ["send-tokens"]) → Get full parameters
3. Call the tool directly

Or use the keplr-guide prompt for a full workflow guide.

Getting Started

New to the wallet? Use the onboarding tools to get set up:

onboarding-status    # Check setup progress and get guidance
/get-started         # Guided onboarding prompt

The server provides intelligent guidance:

• Setup Guide: When wallet isn't configured, tools return setup options instead of errors
• Suggested Actions: Query results include logical next steps (e.g., "stake tokens", "claim rewards")
• Progress Tracking: Checklist-based onboarding status

Account Management

The server supports multiple accounts stored securely in the OS Keychain:

create-account name="trading"              # Create new wallet
import-account name="main" mnemonic="..."  # Import existing
list-accounts                              # List all accounts
switch-account name="trading"             # Switch active account

Configuration is stored in ~/.keplr-mcp/.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | KEPLR_MNEMONIC | No | BIP39 mnemonic (overrides keychain) | | KEPLR_ADAPTERS | No | Additional adapter packages to load (comma-separated) | | KEPLR_RPC_API_KEY | No | Keplr RPC API key for premium endpoints (falls back to public RPC if unset) | | KEPLR_TX_TTL_MINUTES | No | Transaction confirmation token TTL in minutes (default: 5) | | COINGECKO_API_KEY | No | CoinGecko Pro API key for portfolio price data | | SKIP_API_KEY | No | Skip Routes API key for IBC channel resolution | | SKIP_API_URL | No | Skip Routes API endpoint override |

Supported Chains

Cosmos: Cosmos Hub, Osmosis, dYdX, Celestia, Stargaze, Juno, Noble, Stride, Akash, Injective, and 40+ more.

Tool Summary

67 tools and 20+ prompts across categories: Account Management, Cosmos Query & Transaction, CosmWasm, Multi-Action, DeFi (Osmosis), Authentication, Keplr Infra, and more.

For the full tool list and parameters, see the Tool Reference.

Programmatic Usage

import { keyProviderRegistry, adapterBridgeRegistry } from "@keplr-wallet/keplr-wallet-mcp/keys";
import { EcosystemAdapter } from "@keplr-wallet/keplr-wallet-mcp/ecosystem";
import { KeplrStore } from "@keplr-wallet/keplr-wallet-mcp/store";
import { KeplrPlugin, pluginRegistry } from "@keplr-wallet/keplr-wallet-mcp/plugin-types";
import { balanceEnricherRegistry } from "@keplr-wallet/keplr-wallet-mcp/sdk";
import { loadConfig } from "@keplr-wallet/keplr-wallet-mcp/config";
import { getRpcResolver } from "@keplr-wallet/keplr-wallet-mcp/rpc";

Security

• Mnemonics are encrypted with AES-256-GCM and stored in ~/.keplr-mcp/vaults/<account>.enc. The decryption key is stored in your OS credential store (e.g. macOS Keychain)
• All transactions (send, delegate, swap, etc.) require explicit confirmation via confirm-action
• Confirmation tokens expire after 5 minutes
• Use dedicated wallets with limited funds for AI agent usage

Optional: Two-Factor Authentication

For additional security, you can enable authentication for destructive actions (account deletion, mnemonic export). Authentication is handled separately from transaction confirmation — it applies at the tool layer, not via confirm-action. Two methods are available:

Biometric (Touch ID / Face ID)

auth-setup provider=biometric  # Enable biometric auth

TOTP (Google Authenticator)

auth-setup provider=totp       # Step 1: Generate secret key
# Add the key to Google Authenticator app
auth-verify-setup provider=totp code=123456  # Step 2: Verify with 6-digit code

When enabled, you'll need to authenticate before performing protected actions.

TOTP secrets are stored in your OS credential store (e.g. macOS Keychain), not in the config file.

Supported authenticator apps: Google Authenticator, Authy, Microsoft Authenticator, 1Password, and any RFC 6238 compatible app.

License

MIT