@turtleclub/mcp

MCP server for Turtle Earn — DeFi yield opportunities, deposits, wallet connection, and transaction signing via WalletConnect.

Installation

Claude Desktop

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

{
  "mcpServers": {
    "turtle-earn": {
      "command": "npx",
      "args": ["-y", "@turtleclub/mcp"]
    }
  }
}

Claude Code

claude mcp add turtle-earn -- npx -y @turtleclub/mcp

From source

git clone https://github.com/turtle-dao/turtle-mcp.git
cd turtle-mcp
bun install
bun run build

Then point your MCP client to the built server:

{
  "mcpServers": {
    "turtle-earn": {
      "command": "node",
      "args": ["/path/to/turtle-mcp/dist/index.js"]
    }
  }
}

Environment Variables

All optional — the server works out of the box with sensible defaults.

| Variable | Default | Description | |----------|---------|-------------| | EARN_API_URL | https://earn.turtle.xyz | Turtle Earn API base URL | | WALLETCONNECT_PROJECT_ID | Built-in project ID | Override WalletConnect project ID |

Tools

Opportunities

| Tool | Description | |------|-------------| | get_opportunities | List yield opportunities with optional filters (type, chain, APR, TVL). Includes interactive grid UI. | | get_opportunity_by_id | Get full details for a specific opportunity. Includes interactive detail UI with deposit action. | | get_opportunities_by_distributor | Get opportunities for the Turtle distributor. |

Wallet

| Tool | Description | |------|-------------| | connect_wallet | Connect a mobile wallet via WalletConnect. Shows QR code and deep links for MetaMask, Rainbow, and Trust Wallet. | | wallet_status | Check connection status. Returns address and chain ID. | | send_transaction | Send a transaction to the connected wallet for signing. Auto-switches chain if needed. | | sign_message | Sign a message with personal_sign. Used for membership registration. | | disconnect_wallet | Disconnect the wallet session. |

Actions

| Tool | Description | |------|-------------| | create_deposit | Generate deposit transaction data for a yield opportunity. | | create_withdraw | Generate withdrawal transaction data from a yield opportunity. | | claim_deposit | Claim a pending async deposit. | | claim_withdraw | Claim a pending withdrawal. | | cancel_deposit | Cancel a pending async deposit. | | cancel_withdraw | Cancel a pending withdrawal. | | attribute_action | Link an on-chain tx hash to a Turtle action for tracking. | | verify_tracking | Verify that a transaction has Turtle tracking data. |

Deposits & Membership

| Tool | Description | |------|-------------| | get_deposits | Track deposits with optional wallet address filter. | | check_membership | Check if a wallet is a registered Turtle member. | | create_agreement | Generate a signature message for wallet verification (step 1). | | create_membership | Register a new member with a signed message (step 2). |

MCP Apps

The server includes 4 interactive UI apps (rendered in hosts that support MCP Apps):

• Opportunities Dashboard — Grid view of yield opportunities with search and sorting
• Opportunity Detail — Stats cards with deposit flow
• Wallet Connect — QR code scanner and deep links for wallet connection
• Transaction Approval — Transaction preview with status tracking

Testing with MCPJam Inspector

MCPJam Inspector supports MCP Apps rendering and has an LLM Playground for end-to-end testing.

From source

cd turtle-mcp
npx @anthropic-ai/mcpjam-inspector bun run dev

From npm package

npx @anthropic-ai/mcpjam-inspector npx -y @turtleclub/mcp

Example Flow

User: "What are the best lending opportunities?"

Claude: [calls get_opportunities with type=lending, sortBy=apr]
→ Shows interactive grid with opportunities

User: [clicks an opportunity in the grid]

Claude: [calls get_opportunity_by_id]
→ Shows detail card with APR, TVL, chain, deposit tokens

User: "I want to deposit 100 USDC"

Claude: "First, let's connect your wallet."
Claude: [calls connect_wallet]
→ Shows QR code — user scans with MetaMask

Claude: [calls create_deposit]
→ Returns transaction data

Claude: [calls send_transaction]
→ User approves in wallet, tx confirmed

Development

bun install
bun run dev          # Run server directly with Bun
bun run build        # Build apps + server
bun run build:apps   # Build only MCP App UIs
bun run build:server # Build only the MCP server

License

MIT