MCP Server

Overview

Karen exposes all wallet and DeFi capabilities as MCP tools, allowing any MCP-compatible AI agent (like Claude Desktop or OpenClaw) to manage Solana wallets and execute transactions autonomously. The MCP server runs on stdio, making it compatible with:

Claude Desktop (Anthropic)
OpenClaw (AI-powered CLI)
LangChain with MCP support
Any MCP-compatible framework

Karen implements the Model Context Protocol specification from the @modelcontextprotocol/sdk package.

Installation

Clone and build Karen

git clone https://github.com/Don-Vicks/karen.git
cd karen
npm install
npm run build

Set environment variables

Create a .env file:

KEYSTORE_PASSWORD=your-secure-password
SOLANA_NETWORK=devnet

Test the MCP server

npx tsx src/mcp/server.ts

You should see: Karen MCP server running on stdio

Configuration

Claude Desktop

Add Karen to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "karen": {
      "command": "npx",
      "args": ["tsx", "/path/to/karen/src/mcp/server.ts"],
      "env": {
        "KEYSTORE_PASSWORD": "your-secure-password",
        "SOLANA_NETWORK": "devnet"
      }
    }
  }
}

Config file locations:

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

OpenClaw

Add to your .openclaw/config.json:

{
  "mcp": {
    "servers": {
      "karen": {
        "command": "npx",
        "args": ["tsx", "/path/to/karen/src/mcp/server.ts"]
      }
    }
  }
}

Available Tools

Karen exposes 20 MCP tools for wallet and DeFi operations. All tools are prefixed with karen_.

Wallet Management

karen_create_wallet

Create a new managed Solana wallet.Parameters:

name

string

required

Human-readable name for the wallet

Returns:

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-wallet",
  "address": "7xKKzD8qH...",
  "message": "Wallet created. Use karen_airdrop to fund it with devnet SOL."
}

Example usage in Claude:

“Create a new wallet called trading-bot”

karen_list_wallets

List all managed wallets with their addresses and names.Parameters: NoneReturns:

{
  "wallets": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "trading-bot",
      "publicKey": "7xKKzD8qH...",
      "tags": ["mcp", "external"]
    }
  ]
}

karen_balance

Check SOL and SPL token balances for a wallet.Parameters:

walletId

string

required

Wallet ID returned from karen_create_wallet

Returns:

{
  "wallet": "trading-bot",
  "address": "7xKKzD8qH...",
  "sol": 1.5,
  "tokens": [
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "uiBalance": "100.50"
    }
  ]
}

karen_airdrop

Request SOL from the devnet faucet. Devnet only — max 2 SOL per request.Parameters:

walletId

string

required

Wallet ID to fund

amount

number

required

Amount of SOL to request (max 2)

Example:

“Airdrop 2 SOL to my trading-bot wallet”

Transactions

karen_transfer

Send SOL from a managed wallet to any Solana address.Parameters:

walletId

string

required

Source wallet ID

string

required

Recipient Solana address (base58)

amount

number

required

Amount of SOL to send

Returns:

{
  "status": "confirmed",
  "signature": "5Kn8fG...",
  "guardrails": ["spending_limit_check"]
}

Transfers are subject to guardrails:

Max 2 SOL per transaction (default)
Max 5 transactions per minute
Daily spending limit of 10 SOL

karen_swap

Swap tokens using Jupiter DEX aggregator.Parameters:

walletId

string

required

Wallet ID to swap from

inputToken

string

required

Token to sell (e.g., “SOL”, “USDC”, or mint address)

outputToken

string

required

Token to buy (e.g., “USDC”, “BONK”)

amount

number

required

Amount of input token to swap

slippageBps

number

default:"50"

Max slippage in basis points (50 = 0.5%)

Example:

“Swap 0.5 SOL for USDC with 1% slippage”

karen_tx_history

Get transaction history for a wallet.Parameters:

walletId

string

Wallet ID (optional — omit for all wallets)

limit

number

default:"20"

Number of transactions to return

DeFi: Token Launch

karen_launch_token

Create a new SPL token with initial supply. You become the mint and freeze authority.Parameters:

walletId

string

required

name

string

required

Token name (e.g., “Agent Coin”)

symbol

string

required

Token ticker symbol (e.g., “AGT”)

decimals

number

default:"9"

Decimal places

initialSupply

number

default:"1000000"

Initial supply in whole units

Returns:

{
  "name": "Agent Coin",
  "symbol": "AGT",
  "mint": "7xKKzD8qH...",
  "supply": 1000000,
  "signature": "5Kn8fG..."
}

karen_mint_supply

Mint additional tokens for a token you created. Requires mint authority.Parameters:

walletId

string

required

mint

string

required

Token mint address

amount

number

required

Amount to mint

decimals

number

default:"9"

karen_revoke_authority

Permanently revoke mint or freeze authority on a token. IRREVERSIBLE.Parameters:

walletId

string

required

mint

string

required

authorityType

string

default:"mint"

“mint” or “freeze”

This action is permanent and irreversible. Once revoked, you cannot mint new tokens or freeze accounts.

DeFi: Staking

karen_stake

Stake SOL by delegating to a Solana validator.Parameters:

walletId

string

required

amount

number

required

SOL to stake

validator

string

Validator vote account (optional — uses default devnet validator)

Returns:

{
  "stakeAccount": "9xYz...",
  "amount": 1.0,
  "validator": "BeachiopjxQxL7CaHNSZsynRdj6vY5vCeaTXGKqfCZTP",
  "signature": "5Kn8fG..."
}

karen_unstake

Deactivate a stake account. After 1 epoch (~2 days), you can withdraw.Parameters:

walletId

string

required

stakeAccount

string

required

Stake account public key

karen_withdraw_stake

Withdraw SOL from a fully deactivated stake account.Parameters:

walletId

string

required

stakeAccount

string

required

karen_list_stakes

List all stake accounts for a wallet.Parameters:

walletId

string

required

Returns:

{
  "stakes": [
    {
      "address": "9xYz...",
      "solBalance": 1.0,
      "state": "active",
      "voter": "BeachiopjxQxL7CaHNSZsynRdj6vY5vCeaTXGKqfCZTP"
    }
  ]
}

DeFi: Token Account Operations

karen_burn

Burn (destroy) SPL tokens from your wallet.Parameters:

walletId

string

required

mint

string

required

amount

number

required

karen_close_account

Close an empty token account to reclaim rent SOL (~0.002 SOL).Parameters:

walletId

string

required

mint

string

required

karen_wrap_sol

Convert SOL to Wrapped SOL (wSOL) for DeFi interactions.Parameters:

walletId

string

required

amount

number

required

karen_unwrap_sol

Convert all wSOL back to native SOL.Parameters:

walletId

string

required

Usage Examples

In Claude Desktop

Once configured, you can use natural language to interact with Karen:

Create & Fund Wallet
Token Swap
Launch Token

You: Create a new wallet called “trading-agent” and fund it with 2 SOLClaude: I’ll create the wallet and request an airdrop.Claude calls:

karen_create_wallet({"name": "trading-agent"})
karen_airdrop({"walletId": "...", "amount": 2})

Claude: Done! Your wallet “trading-agent” is funded with 2 SOL.

You: Swap 0.5 SOL for USDCClaude: I’ll execute the swap using Jupiter DEX.Claude calls:

karen_balance({"walletId": "..."})
karen_swap({"walletId": "...", "inputToken": "SOL", "outputToken": "USDC", "amount": 0.5})

Claude: Swapped 0.5 SOL for 19.23 USDC.

You: Create a token called “Bot Coin” with symbol BTC, 1M initial supplyClaude: I’ll launch your token.Claude calls: karen_launch_token({"walletId": "...", "name": "Bot Coin", "symbol": "BTC", "initialSupply": 1000000})Claude: Token launched! Mint address: 7xKKz… (1,000,000 BTC minted to your wallet)

Security & Guardrails

All MCP tools pass through Karen’s guardrails before execution:

Spending Limits

Max 2 SOL per transaction
Daily cap of 10 SOL

Rate Limiting

Max 5 transactions per minute

Program Whitelist

Only approved Solana programs
System, Token, Jupiter, Staking

Audit Logging

All transactions logged
Full history available via karen_tx_history

The default password is karen-dev. Change this in production by setting KEYSTORE_PASSWORD in your environment.

Troubleshooting

MCP server not showing in Claude Desktop

Check the config file location for your OS
Verify the path to server.ts is absolute
Restart Claude Desktop completely
Check logs: ~/Library/Logs/Claude/mcp*.log (macOS)

Airdrop fails with 'rate limit exceeded'

Devnet faucet has rate limits. Wait 1-2 minutes and try again.

Transaction blocked by guardrails

Check the error message in the tool response. Common causes:

Amount exceeds maxSolPerTransaction (2 SOL default)
Daily spending limit reached
Rate limit exceeded (5 tx/min)

Adjust limits in src/core/transaction/guardrails.ts if needed.

Next Steps

REST API

Integrate Karen via HTTP endpoints

TypeScript SDK

Use Karen as a library in your Node.js app

API Reference

Detailed endpoint documentation

Guardrails

Configure security policies

Get Started

Core Concepts

Integration

Agent Skills

Development

Overview

Installation

Configuration

Claude Desktop

OpenClaw

Available Tools

Wallet Management

Transactions

DeFi: Token Launch

DeFi: Staking

DeFi: Token Account Operations

Usage Examples

In Claude Desktop

Security & Guardrails

Spending Limits

Rate Limiting

Program Whitelist

Audit Logging

Troubleshooting

Next Steps

REST API

TypeScript SDK

API Reference

Guardrails

Build docs developers (and LLMs) love

Get Started

Core Concepts

Integration

Agent Skills

Development

​Overview

​Installation

​Configuration

​Claude Desktop

​OpenClaw

​Available Tools

​Wallet Management

​Transactions

​DeFi: Token Launch

​DeFi: Staking

​DeFi: Token Account Operations

​Usage Examples

​In Claude Desktop

​Security & Guardrails

Spending Limits

Rate Limiting

Program Whitelist

Audit Logging

​Troubleshooting

​Next Steps

REST API

TypeScript SDK

API Reference

Guardrails

Build docs developers (and LLMs) love

Overview

Installation

Configuration

Claude Desktop

OpenClaw

Available Tools

Wallet Management

Transactions

DeFi: Token Launch

DeFi: Staking

DeFi: Token Account Operations

Usage Examples

In Claude Desktop

Security & Guardrails

Troubleshooting

Next Steps