solblade

<p align="center"> <img src="banner.png" alt="Solblade" width="700" /> </p>

<p align="center"> <strong>AI-native Solana wallet CLI with scoped MCP server</strong><br/> Your keys. Their hands. Your rules. </p>

<p align="center"> <a href="https://github.com/nullxnothing/solblade/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/nullxnothing/solblade/ci.yml?style=flat-square&label=CI" alt="CI" /></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license" /></a> <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f472b6?style=flat-square" alt="bun" /></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/protocol-MCP-7c3aed?style=flat-square" alt="MCP" /></a> <a href="https://github.com/nullxnothing/solblade/stargazers"><img src="https://img.shields.io/github/stars/nullxnothing/solblade?style=flat-square&color=f5c542" alt="stars" /></a> </p>

<p align="center"> <a href="#install">Install</a> • <a href="#connect-to-your-ai">Connect to your AI</a> • <a href="#mcp-tools">MCP Tools</a> • <a href="#security-model">Security</a> • <a href="#cli-commands">CLI Commands</a> • <a href="#architecture">Architecture</a> </p>

---

<p align="center"> <img src="demo.png" alt="Solblade terminal demo" width="780" /> </p>

---

Solblade is a Solana wallet that runs in your terminal and exposes a Model Context Protocol (MCP) server so AI agents can manage your wallets — with granular, per-wallet permission scoping you control.

No browser extensions. No custodial APIs. Just a CLI with an encrypted local keystore and an MCP interface that gives AI exactly the access you choose: read-only portfolio views, spend-limited transfers, or full autonomy within guardrails.

Why Solblade

AI agents need wallet access to be useful on-chain, but giving an AI your private key is insane — and read-only access is useless for real work.

Solblade sits between your keys and the AI. You set per-wallet access levels, spend limits, rate limits, and destination allowlists. The AI operates within those bounds. Every action is logged in a tamper-evident audit chain. Revoke access with one command.

• CLI-native MCP server — no web app, no browser extension, just solblade mcp serve
• Per-wallet AI permissions — each wallet has its own access level and spend limits
• Confirmation gates — require human approval for transfers, or auto-execute under limits
• Rent reclaim engine — AI scans for dead token accounts and reclaims locked SOL in bulk
• Tamper-evident audit log — SHA-256 chained event log of every AI action
• Encrypted local keystore — AES-256-GCM with PBKDF2 key derivation, keys never leave your machine

---

Install

# requires Bun (https://bun.sh)
bun install -g solblade

# initialize keystore, first wallet, and RPC config
solblade init

---

Connect to your AI

Solblade works with any MCP-compatible client. Pick your editor below.

Tip: Replace "*" with specific tool groups to restrict access — "read" for read-only, "read,scan,cleanup" for read + rent reclaim.

<details> <summary><strong>Claude Code</strong></summary>

claude mcp add solblade -- bunx solblade mcp serve --allow "*"

That's it. One command.

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "solblade": {
      "command": "bunx",
      "args": ["solblade", "mcp", "serve", "--allow", "*"]
    }
  }
}

Restart Claude Desktop after saving.

</details>

<details> <summary><strong>Cursor</strong></summary>

Add to .cursor/mcp.json in your project root, or go to Settings > MCP Servers > Add Server:

{
  "mcpServers": {
    "solblade": {
      "command": "bunx",
      "args": ["solblade", "mcp", "serve", "--allow", "*"]
    }
  }
}

</details>

<details> <summary><strong>VS Code / GitHub Copilot</strong></summary>

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "solblade": {
      "command": "bunx",
      "args": ["solblade", "mcp", "serve", "--allow", "*"]
    }
  }
}

Or open the Command Palette (Ctrl+Shift+P) and run MCP: Add Server.

</details>

<details> <summary><strong>Windsurf</strong></summary>

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "solblade": {
      "command": "bunx",
      "args": ["solblade", "mcp", "serve", "--allow", "*"]
    }
  }
}

</details>

<details> <summary><strong>Zed</strong></summary>

Add to Zed settings (settings.json):

{
  "context_servers": {
    "solblade": {
      "command": {
        "path": "bunx",
        "args": ["solblade", "mcp", "serve", "--allow", "*"]
      }
    }
  }
}

</details>

<details> <summary><strong>Any MCP Client (stdio)</strong></summary>

Solblade speaks MCP over stdio. Point any compatible client at:

bunx solblade mcp serve --allow "*"

</details>

---

MCP Tools

Once connected, your AI agent has access to these tool groups:

Group	Tools	What it does
balance	get_balance get_all_balances get_token_balances	SOL and token balance queries
wallets	list_wallets get_wallet_permissions	Wallet metadata and AI access levels
price	get_token_price	USD prices via Jupiter/Birdeye
swap	get_swap_quote execute_swap	Jupiter DEX quotes and execution
transfer	send_sol send_token	SOL and SPL token transfers
scan	scan_empty_accounts scan_all_wallets estimate_portfolio_value	Rent reclaim scanning, portfolio valuation
cleanup	close_token_account close_token_accounts_bulk	Close dead token accounts, reclaim rent
history	get_transaction_history get_account_info	On-chain transaction and account data
log	get_audit_log get_spend_summary	AI action history and spend tracking
admin	get_session_status	Session and permission introspection

Permission Scoping

Every wallet has independent AI access controls:

# Read-only access
solblade wallet ai-access treasury --level read

# Transfer access with spend limits (SOL)
solblade wallet ai-access trading --level transfer --per-tx 1 --per-session 5

# Require human confirmation for each transfer
solblade wallet set-confirm trading --on

# Restrict destinations to trusted addresses
solblade wallet set-allowlist trading --add <trusted-pubkey>

Confirmation Flow

When require_confirmation is enabled, write tools return a pending action instead of executing:

AI:  "I'd like to send 0.5 SOL from 'trading' to 9xQe...4kPm ($75.00).
      This is within your 1 SOL per-transaction limit. Approve?"
You: "Yes"
AI:  "Done — tx confirmed: 5Uj8... (explorer link)"

---

Security Model

┌─ Tool Allowlist ────────── which tools are exposed at all
├─ Wallet AI Access ──────── none / read / transfer per wallet
├─ Session Gate ──────────── password-derived key, configurable TTL
├─ Spend Limits ──────────── per-tx and per-session caps in SOL
├─ Rate Limits ───────────── max transactions per minute
├─ Destination Allowlist ─── restrict where funds can go
├─ Confirmation Gate ─────── human approval before execution
├─ Transaction Simulation ── Solana RPC simulation before signing
└─ Tamper-Evident Audit ──── SHA-256 chained event log

Never exposed via MCP: private key export, seed phrases, keystore files, password/session material, permission escalation, wallet creation/deletion, RPC config changes.

---

CLI Commands

Wallet Management

solblade create [--label name] [--group name]     # Create new wallet
solblade import --key <base58>                     # Import existing key
solblade list [--group name] [--tag name]          # List wallets
solblade label <wallet> --set <name>               # Rename wallet
solblade default <wallet>                          # Set default wallet
solblade remove <wallet>                           # Archive wallet

Transactions

solblade balance [wallet]                          # SOL balance
solblade balance --all                             # All wallet balances
solblade balance --tokens [wallet]                 # SPL token balances
solblade send <amount> SOL --to <address>          # Send SOL
solblade send <amount> <token> --to <address>      # Send SPL token
solblade swap <amount> <token> --to <token>        # Jupiter swap

Session & Security

solblade unlock                                    # Start session
solblade lock                                      # End session
solblade unlock --status                           # Check session

MCP Server

solblade mcp serve [--allow <tools>]               # Start MCP stdio server

Audit

solblade log [--limit N]                           # View audit log

---

Architecture

Component	Stack
Runtime	Bun with native SQLite
Encryption	AES-256-GCM, PBKDF2-SHA256 (600k iterations)
Database	SQLite with WAL mode
MCP	@modelcontextprotocol/sdk over stdio
Solana	@solana/web3.js v1.x + @solana/spl-token v0.4
DEX	Jupiter V6 API
Keystore	~/.solblade/keys/*.enc (one encrypted file per wallet)

See docs/MCP_ARCHITECTURE.md for the full MCP server design.

---

Development

git clone https://github.com/nullxnothing/solblade.git
cd solblade
bun install
bun run dev

License

MIT

---

<p align="center"> <img src="logo.png" alt="Solblade logo" width="48" /> </p>