Purple Flea

Posted on Mar 1

How to connect AI agents to crypto APIs using MCP (Model Context Protocol)

#ai #mcp #crypto #tutorial

Step-by-Step: Setting Up Purple Flea MCP Servers for Claude Desktop

The Model Context Protocol (MCP) lets Claude Desktop call external tools directly. Purple Flea ships four MCP servers that give Claude native access to trading, casino, wallet, and identity APIs — no code required. This tutorial walks through the full setup from zero to a working agent that can trade 275+ markets from a chat interface.

Prerequisites

Before starting, you'll need:

Claude Desktop installed (download)
Node.js 18+ installed (node --version to check)
A Purple Flea API key from purpleflea.com

Verify Node.js is available:

node --version
# v20.11.0 or higher

npx --version
# 10.2.0 or higher

If you don't have Node.js, install it from nodejs.org or via your package manager:

# macOS
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows (winget)
winget install OpenJS.NodeJS.LTS

Step 1: Locate the Claude Desktop Config File

Claude Desktop stores its MCP server configuration in a JSON file. The location depends on your OS:

OS	Config Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Open this file in your editor. If it doesn't exist yet, create it:

# macOS
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
mkdir -p ~/.config/Claude
touch ~/.config/Claude/claude_desktop_config.json

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:APPDATA\Claude"
New-Item -ItemType File -Force -Path "$env:APPDATA\Claude\claude_desktop_config.json"

Step 2: Add Purple Flea MCP Servers

Open the config file and add the Purple Flea servers. If the file is empty or doesn't have a mcpServers key, start with this full configuration:

{
  "mcpServers": {
    "purple-flea-trading": {
      "command": "npx",
      "args": ["-y", "@purple-flea/trading-mcp"],
      "env": {
        "PF_API_KEY": "pf_live_your_key_here"
      }
    },
    "purple-flea-casino": {
      "command": "npx",
      "args": ["-y", "@purple-flea/casino-mcp"],
      "env": {
        "PF_API_KEY": "pf_live_your_key_here"
      }
    },
    "purple-flea-wallet": {
      "command": "npx",
      "args": ["-y", "@purple-flea/wallet-mcp"],
      "env": {
        "PF_API_KEY": "pf_live_your_key_here"
      }
    },
    "purple-flea-identity": {
      "command": "npx",
      "args": ["-y", "@purple-flea/identity-mcp"],
      "env": {
        "PF_API_KEY": "pf_live_your_key_here"
      }
    }
  }
}

Replace pf_live_your_key_here with your actual API key in all four entries.

If you already have other MCP servers configured, merge the Purple Flea entries into your existing mcpServers object:

{
  "mcpServers": {
    "your-existing-server": {
      "command": "...",
      "args": ["..."]
    },
    "purple-flea-trading": {
      "command": "npx",
      "args": ["-y", "@purple-flea/trading-mcp"],
      "env": {
        "PF_API_KEY": "pf_live_your_key_here"
      }
    }
  }
}

Tip: You don't need to install all four servers. If you only need trading, just add purple-flea-trading. Each server is independent.

Step 3: Restart Claude Desktop

MCP servers are loaded at startup. After saving the config file:

Fully quit Claude Desktop (not just close the window — quit the app)
Reopen Claude Desktop
Wait 5-10 seconds for MCP servers to initialize

Step 4: Verify the Connection

In a new Claude Desktop conversation, you should see the MCP tools available. Look for the hammer icon (tools) in the input area — clicking it should show Purple Flea tools.

Verify by asking Claude to list available markets:

Show me the available trading markets on Purple Flea

Claude should call the list_markets tool and return a list of 275+ perpetual futures markets across crypto, stocks, commodities, and forex.

If you don't see the tools, check the MCP server logs:

# macOS — check Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log

# Or check if the MCP package is accessible
npx -y @purple-flea/trading-mcp --version

Common issues:

"command not found: npx" — Node.js isn't in Claude Desktop's PATH. Try using the full path: "command": "/usr/local/bin/npx"
JSON syntax error — Validate your config at jsonlint.com
Timeout on startup — First run downloads packages via npx; allow 30 seconds

Step 5: Your First Trade via Claude

Now the fun part. Ask Claude to execute a trade:

Buy 0.001 BTC-PERP with a stop loss at $60,000 and take profit at $72,000

Claude will:

Call the place_order tool with your parameters
Show you the order details before executing (Claude asks for confirmation)
Return the fill price, order ID, and position details

You can also ask Claude to check positions:

Show me my open positions and their unrealized P&L

Or manage risk:

Close my ETH-PERP position with a market order

Step 6: Casino Games via MCP

With the casino server configured, you can play provably fair games directly in chat:

Flip a coin for 1 USDC on heads, use "my-seed-123" as the client seed

Claude will call the coinflip tool and return:

The outcome (heads/tails)
Your payout
The server seed hash (committed before the bet)
The revealed server seed (for verification)

You can then verify fairness:

Verify the last coinflip result was fair using the seeds provided

Step 7: Wallet Operations

The wallet MCP server lets Claude manage your agent's wallet:

What's my current USDC balance?

Send 5 USDC to 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18

The wallet server enforces spending limits and allowlists configured on your API key, so even if Claude decides to send funds, it can only operate within your predefined guardrails.

Available MCP Tools Reference

Each server exposes specific tools that Claude can call:

Trading MCP

Tool	Description
`list_markets`	Get all 275+ available markets with leverage limits
`place_order`	Place market, limit, or conditional orders
`get_positions`	View open positions with P&L
`close_position`	Close a specific position
`get_order_history`	View recent order history

Casino MCP

Tool	Description
`coinflip`	Bet on heads or tails (2x payout)
`dice`	Roll over/under a target (variable payout)
`crash`	Set cashout multiplier (variable payout)
`blackjack_start`	Start a blackjack hand
`blackjack_action`	Hit, stand, double, or split
`verify_result`	Cryptographically verify any game outcome

Wallet MCP

Tool	Description
`get_balance`	Check token balances
`send_tokens`	Transfer tokens (within allowlist/limits)
`get_transactions`	View transaction history

Identity MCP

Tool	Description
`get_identity`	Retrieve agent identity info
`verify_key`	Verify API key status and scopes

Advanced: Using a System Prompt

For more structured agent behavior, start your Claude Desktop conversation with a system-level instruction:

You are a conservative trading agent. You may only:
- Trade BTC-PERP and ETH-PERP
- Use maximum 3x leverage
- Never risk more than 2% of portfolio on a single trade
- Always set stop losses

Before every trade, explain your reasoning and wait for my confirmation.

Claude will follow these constraints while using the MCP tools, giving you a conversational trading interface with built-in risk management.

Troubleshooting

MCP servers don't appear after restart:
Verify the config JSON is valid and the file is in the correct location. Run npx -y @purple-flea/trading-mcp --version manually to confirm the package resolves.

"Authentication failed" errors:
Check that your PF_API_KEY in the config doesn't have extra whitespace or quotes around the value.

Slow first response:
The first tool call after startup triggers npx to download the package. Subsequent calls use the cached version and are faster.

Tools work but trades fail:
Verify your API key has the correct scopes (trading, casino, wallet) and that your account is funded.

Docs: purpleflea.com/llms.txt
GitHub: github.com/Purple-flea
MCP Packages: @purple-flea/trading-mcp · @purple-flea/casino-mcp · @purple-flea/wallet-mcp · @purple-flea/identity-mcp

DEV Community