@cobbee/mcp-server

MCP (Model Context Protocol) server for Cobbee - Enable AI agents to send crypto tips to creators using the x402 payment protocol.

Overview

This MCP server allows AI assistants like Claude to interact with the Cobbee platform and make USDC payments to creators on the Base network. It uses the x402 payment protocol to handle 402 Payment Required flows seamlessly.

Features

• Send Coffee: Tip creators with USDC on Base network
• Buy Products: Purchase digital products from creators
• Search Creators: Find creators by name or username
• Get Creator Profile: View detailed creator information
• List Products: Browse available products
• Wallet Management: Check balance and address

Prerequisites

• Node.js >= 20.0.0
• An Ethereum wallet with USDC on Base network
• Your wallet's private key (for signing transactions)

Installation

Option 1: Install from npm (when published)

npm install -g @cobbee/mcp-server

Option 2: Build from source

cd packages/mcp-server
pnpm install
pnpm build

Configuration

Environment Variables

Create a .env file or set these environment variables:

# Required: Your wallet's private key (with 0x prefix)
WALLET_PRIVATE_KEY=0x...

# Optional: Cobbee API URL (defaults to https://cobbee.fun)
COBBEE_API_URL=https://cobbee.fun

# Optional: Network selection (defaults to "base")
# Use "base" for mainnet, "base-sepolia" for testnet
NETWORK=base

Claude Desktop Configuration

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "cobbee": {
      "command": "npx",
      "args": ["-y", "@cobbee-mcp/server"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x...",
        "NETWORK": "base"
      }
    }
  }
}

Or if built from source:

{
  "mcpServers": {
    "cobbee": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x...",
        "NETWORK": "base"
      }
    }
  }
}

Cursor IDE Configuration

Cursor also supports MCP servers. Create a .cursor/mcp.json file in your project directory:

{
  "mcpServers": {
    "cobbee": {
      "command": "npx",
      "args": ["-y", "@cobbee-mcp/server"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x...",
        "NETWORK": "base"
      }
    }
  }
}

Setup steps for Cursor:

1. Create the .cursor directory in your project root:

   mkdir -p .cursor

2. Create .cursor/mcp.json with the configuration above

3. Enable MCP in Cursor:

   • Go to Settings > Cursor Settings > MCP Servers
   • Toggle Enable to on

4. Switch to Agent Mode in Cursor chat (MCP tools only work in Agent Mode, not Ask Mode)

5. Verify the connection - the MCP server indicator should turn green

Available Tools

send_coffee

Send a coffee tip (USDC) to a Cobbee creator.

Parameters:

• username (required): Creator's username on Cobbee
• coffeeCount (optional, default: 1): Number of coffees to send (1-100)
• message (optional): Message to the creator (max 500 characters)
• isPrivate (optional, default: false): Make the message private

Example usage in Claude:

"Send 3 coffees to @johndoe with the message 'Love your work!'"

buy_product

Purchase a digital product from a Cobbee creator.

Parameters:

• productId (required): The product's UUID
• supporterName (optional): Your display name for the purchase

Example usage in Claude:

"Buy the product with ID abc123-def456..."

search_creators

Search for creators on Cobbee.

Parameters:

• query (optional): Search query for name/username
• limit (optional, default: 10): Maximum results (1-50)

Example usage in Claude:

"Search for creators related to 'digital art'"

get_creator

Get detailed information about a specific creator.

Parameters:

• username (required): Creator's username

Example usage in Claude:

"Get profile information for @johndoe"

get_products

List products available for purchase.

Parameters:

• username (optional): Filter by creator username
• limit (optional, default: 10): Maximum results (1-50)

Example usage in Claude:

"List products from @johndoe"

get_wallet_balance

Get the USDC balance of the configured wallet.

Example usage in Claude:

"What's my wallet balance?"

get_wallet_address

Get the wallet address configured for payments.

Example usage in Claude:

"What's my wallet address?"

Security Considerations

1. Private Key Storage: Never commit your private key to version control. Use environment variables or secure secret management.

2. Amount Limits: The MCP server enforces reasonable limits (max 100 coffees per transaction) to prevent accidental large payments.

3. Network Confirmation: Always verify you're on the correct network (mainnet vs testnet) before making payments.

4. Transaction Verification: All payments use the x402 protocol which ensures proper verification before settlement.

How x402 Payment Works

1. When you request a payment (send_coffee, buy_product), the MCP server makes a request to Cobbee's API
2. The API responds with 402 Payment Required and payment details
3. The x402-wrapped axios client automatically signs the payment with your wallet
4. The signed payment is sent back to complete the transaction
5. The payment is verified and settled on the Base blockchain

Troubleshooting

"WALLET_PRIVATE_KEY environment variable is required"

Make sure you've set the WALLET_PRIVATE_KEY environment variable with your wallet's private key (including the 0x prefix).

"Insufficient balance"

Your wallet doesn't have enough USDC to complete the payment. Use get_wallet_balance to check your balance.

"Creator not found"

The username doesn't exist on Cobbee. Try search_creators to find the correct username.

"Payment failed"

This could be due to network issues or insufficient gas. Make sure you have:

• Enough USDC for the payment
• Some ETH for gas fees on Base network

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Type check
pnpm typecheck

License

MIT

Links

• Cobbee Platform
• x402 Protocol
• Model Context Protocol
• Base Network