Coinbase Chat MCP

Access cryptocurrency data, market information, and trading insights from Coinbase's public API.

GitHub

Coinbase Chat MCP

MIT License TypeScript Model Context Protocol

An open-source Model Context Protocol (MCP) server and web application for seamless integration with Coinbase's public API. This project enables AI agents, LLMs, and developers to interact with cryptocurrency data, market information, and trading insights through a standardized, secure interface.

🎯 What's Real vs. Simulated?

ComponentStatusSource
💰 Cryptocurrency Prices✅ RealCoinbase Public API
📊 Market Statistics✅ RealCoinbase Public API
📈 Historical Data✅ RealCoinbase Public API
🤖 GPT-4 AI Chat✅ RealOpenAI
🎤 Voice Input (Whisper)✅ RealOpenAI
🔊 Text-to-Speech✅ RealOpenAI
🔌 MCP Protocol✅ RealOfficial SDK
💵 Wallet Balances🎮 SimulatedIn-memory demo
💸 Transactions🎮 SimulatedEducational only
🍺 Beer Purchases🎮 SimulatedVirtual economy

Perfect for learning crypto without financial risk! 🎓

🌟 Features

🔌 MCP Server

  • Full MCP Compliance - Implements complete Model Context Protocol specification
  • 13 Powerful Tools - Real-time prices, historical data, market stats, asset search, technical analysis, and transaction simulation
  • 🍺₿ Circular Economy - Complete flow: USD → Crypto → Virtual Beer!
  • Smart Suggestions - AI guides you to buy crypto if needed before purchases
  • Virtual Wallet & Inventory - Track balances, transactions, and beer collection
  • Cursor Integration - Pre-configured for Cursor IDE with .cursor/mcp.json
  • Claude Desktop Compatible - Works with any MCP-compatible client
  • Secure & Fast - Built-in rate limiting and intelligent caching

💬 Interactive Chat Interface

  • AI-Powered Conversations - GPT-4 integration for intelligent crypto discussions
  • Voice Input - Speak your questions with multi-language support via OpenAI Whisper
  • Text-to-Speech - AI responses read aloud with natural voices
  • Session Persistence - Chat history saved across browser tabs and restarts
  • Session Management - Create, switch, and manage multiple chat sessions
  • Auto-Titling - Sessions automatically titled from first user message
  • Real-time Sync - Live updates when switching between sessions

🚀 API Explorer

  • Interactive Documentation - Live testing interface for all 8 MCP tools
  • Real-time Testing - Execute API calls directly from the browser
  • Code Generation - Auto-generated cURL and JavaScript examples
  • Copy-to-Clipboard - Easy code sharing and integration
  • Comprehensive Coverage - All endpoints documented with parameters and examples

🎨 Modern Frontend

  • Beautiful UI - Clean, responsive design with TailwindCSS
  • Real-time Data - Live cryptocurrency prices and market updates
  • Multiple Pages - Dashboard, Markets, Assets, Analysis, Chat, and API Explorer
  • Mobile Friendly - Responsive design works on all devices

🚀 Quick Start

Prerequisites

  • Node.js 18+
  • npm 9+

Installation

  1. Clone the repository

    git clone https://github.com/your-username/coinbase-chat-mcp.git
cd coinbase-chat-mcp

  2. Install dependencies

    npm install
# Install dependencies for all workspaces
cd mcp-server && npm install && cd ..
cd frontend && npm install && cd ..
cd api-server && npm install && cd ..

  3. Configure environment variables (Optional for AI features)

    cd frontend
# Create .env file with your OpenAI API key for voice features
echo "VITE_OPENAI_API_KEY=your_openai_api_key_here" > .env
cd ..

  4. Build the MCP server

    cd mcp-server
npm run build
cd ..

  5. Start development servers

    # Start API server (port 3002)
cd api-server && npm run dev &

# Start frontend (port 5173)
cd frontend && npm run dev &

🤖 MCP Integration

Cursor IDE Setup (Recommended)

The project includes pre-configured Cursor MCP settings:

  1. Automatic Configuration - .cursor/mcp.json is already configured
  2. Restart Cursor - MCP server will auto-load with 8 tools available
  3. Test Integration - Try asking: "What's the current Bitcoin price?"

Claude Desktop Setup

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "coinbase-mcp": {
      "command": "node",
      "args": ["/path/to/coinbase-chat-mcp/mcp-server/dist/index.js"],
      "env": {
        "COINBASE_API_URL": "https://api.coinbase.com/v2",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Available MCP Tools

📊 Market Data Tools (8)

  1. get_spot_price - Current cryptocurrency prices
  2. get_historical_prices - Historical price data with time ranges
  3. get_exchange_rates - Fiat currency exchange rates
  4. search_assets - Find cryptocurrencies and assets
  5. get_asset_details - Detailed asset information
  6. get_market_stats - 24-hour market statistics
  7. get_popular_pairs - Popular trading pairs
  8. analyze_price_data - Technical analysis (volatility, trends, support/resistance)

🍺₿ Demo Transaction Tools (5) - NEW!

  1. calculate_beer_cost - Convert beer money to crypto amounts
  2. simulate_btc_purchase - Simulate buying crypto with USD
  3. buy_virtual_beer 🔥 - Buy virtual beer WITH crypto! (Circular economy)
  4. get_virtual_wallet - View demo wallet balance and stats
  5. get_transaction_history - View simulated transaction history

🎯 Try asking: "Buy me a beer!" → AI will guide you through USD→BTC→Beer! 📖 Full docs: DEMO_TRANSACTIONS.md • CIRCULAR_ECONOMY.md

🏗️ Architecture

System Overview

This project uses a hybrid architecture combining:

  • Real market data from Coinbase Public API
  • Simulated wallet for educational crypto transactions
  • Official MCP protocol for AI agent integration
  • Modern web stack for beautiful UX
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ Cursor IDE  │  │ Web Browser │  │Claude Desktop│
│ (MCP Client)│  │ (React App) │  │ (MCP Client)│
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │
       └────────────────┴────────────────┘
                        │
       ┌────────────────┴────────────────┐
       │                                 │
       ▼                                 ▼
┌──────────────┐              ┌──────────────────┐
│  MCP Server  │              │   API Server     │
│  (13 tools)  │              │   (REST API)     │
└──────┬───────┘              └────────┬─────────┘
       │                               │
       └───────────┬───────────────────┘
                   │
       ┌───────────┴───────────┐
       │                       │
       ▼                       ▼
┌──────────────┐      ┌─────────────────┐
│ Coinbase API │      │ Demo Wallet     │
│ (Real Data)  │      │ (Simulated)     │
└──────────────┘      └─────────────────┘

📖 Detailed Architecture: See ARCHITECTURE.md for:

  • Component diagrams
  • Code examples
  • Real vs. simulated breakdown
  • Comparison with Base MCP and x402
  • Technical deep dive

Key Components

coinbase-chat-mcp/
├── mcp-server/          # MCP Protocol Server (13 tools)
├── api-server/          # Express REST API Server  
├── frontend/            # React + TypeScript Frontend
│   ├── src/pages/       # Chat, Wallet, API Explorer
│   ├── src/components/  # Reusable UI components
│   └── src/services/    # AI, Voice, Chat sessions
├── docs/                # Comprehensive documentation
└── .cursor/             # Cursor IDE MCP configuration

MCP Server

Exposes 13 tools through Model Context Protocol:

Market Data Tools (8):

  • Real-time prices, historical data, market stats
  • Asset search and details, exchange rates
  • Technical analysis (volatility, trends, support/resistance)

Transaction Tools (5):

  • 🍺₿ Beer-to-crypto calculator
  • Virtual wallet simulation (USD → Crypto)
  • Circular economy (Crypto → Beer!)
  • Balance & transaction history

Frontend Application

Modern React application featuring:

  • AI Chat - GPT-4 powered with voice input 🎤 and TTS 🔊
  • Virtual Wallet - Demo crypto purchases and beer economy 🍺₿
  • API Explorer - Interactive documentation and testing
  • Tutorial - Step-by-step MCP integration guide
  • Presentations - Business slide deck viewer

🔧 Configuration

Environment Variables

Create .env files for AI chat functionality:

# frontend/.env (Optional - for AI chat)
VITE_OPENAI_API_KEY=your_openai_api_key_here

Security Note: The frontend includes built-in warnings about client-side API key usage and only enables AI features in development mode.

🤖 AI Chat & Voice Features Setup (Optional)

To enable the AI-powered chat interface with voice capabilities:

  1. Get OpenAI API Key: Visit OpenAI Platform
  2. Create frontend/.env file: 
    VITE_OPENAI_API_KEY=sk-your-actual-api-key-here
  3. Restart the frontend: Chat will use GPT-4 for intelligent crypto discussions!

🎤 Voice Features (Requires OpenAI API Key)

Once configured, you'll have access to:

  • 🌐 Multi-Language Voice Input - Speak questions in any language using OpenAI Whisper

    • Supports 50+ languages including English, Spanish, French, German, Russian, Chinese, Japanese, and more
    • Real-time speech-to-text transcription
    • Click the purple microphone button to start recording

  • 🔊 Text-to-Speech Responses - Hear AI responses read aloud

    • Click the speaker icon on any assistant message
    • Natural-sounding voices powered by OpenAI TTS
    • Multiple voice options available

  • ⚡ Fallback Mode - Without OpenAI key, basic Web Speech API provides English-only voice input

Note: Without the API key, the chat interface provides a helpful setup message and basic functionality.

📚 Usage Examples

MCP Tools in Cursor/Claude

User: "What's the current Bitcoin price?"
Response: Current BTC-USD price: $100,608.65 USD

User: "Show me Ethereum's price trend over the last 7 days"
Response: [Historical price data with analysis]

User: "Analyze Bitcoin's volatility this month"
Response: [Technical analysis with volatility metrics]

User: "Buy me a beer worth of Bitcoin!" 🍺
Response: At $110,360 per BTC, $5 = 0.00004531 BTC
          ✅ Purchased! You now have 0.00004531 BTC

User: "Now buy a beer WITH that Bitcoin!"
Response: 🍺 Beer Purchased with Crypto!
          Paid: 0.00004531 BTC
          Received: 1 🍺
          🎉 Total beers in inventory: 1

User: "Show my wallet"
Response: 👛 Virtual Wallet
          💵 USD: $995.00
          🪙 BTC: 0.00000000
          🍺 Beers: 1
          Total transactions: 2

Frontend Web Application

  • Visit: http://localhost:3005
  • Chat: Persistent conversations with session management
  • Voice Chat: Click microphone to ask questions by voice in any language
  • Listen to Responses: Click speaker icon on messages to hear them read aloud
  • API Explorer: Test all 8 MCP tools interactively
  • Dashboard: Real-time market overview
  • Markets: Detailed trading statistics

Direct API Usage

# Get current Bitcoin price
curl http://localhost:3002/api/v1/prices/BTC-USD

# Search for assets
curl http://localhost:3002/api/v1/assets/search?query=bitcoin

🛠️ Development

Key Features Implemented

  • ✅ MCP Server - 13 tools, full protocol compliance
  • ✅ Cursor Integration - Pre-configured MCP setup
  • ✅ Circular Economy 🍺₿ - Complete USD→Crypto→Beer simulation
  • ✅ Voice Interface 🎤 - Multi-language input via Whisper
  • ✅ Text-to-Speech 🔊 - AI responses read aloud
  • ✅ Virtual Wallet - Demo crypto purchases and inventory
  • ✅ Chat Sessions - Persistent conversations with localStorage
  • ✅ API Explorer - Interactive documentation for all tools
  • ✅ Session Management - Create, switch, delete chat sessions
  • ✅ AI Integration - GPT-4 powered conversations with tool orchestration
  • ✅ Transaction UI - Beautiful receipts and visual feedback
  • ✅ Security - Rate limiting, validation, error handling

Development Scripts

# Build MCP server
cd mcp-server && npm run build

# Start API server (development)
cd api-server && npm run dev

# Start frontend (development)  
cd frontend && npm run dev

# Test MCP server
cd mcp-server && npm test

Project Structure

  • mcp-server/: TypeScript MCP server with 13 tools (8 market data + 5 wallet)
  • api-server/: Express.js REST API server with wallet simulation
  • frontend/: React + TypeScript with TailwindCSS, voice features, wallet UI
  • docs/: Comprehensive documentation (ARCHITECTURE.md, guides, etc.)
  • .cursor/: Cursor IDE MCP configuration

📖 Documentation

Core Documentation

  • README.md - This file! Project overview and quick start
  • ARCHITECTURE.md 🏗️ - Complete technical architecture guide
    • System diagrams and component breakdown
    • Real vs. simulated components explained
    • Code examples and data flow
    • Comparison with Base MCP and x402
    • Technology stack deep dive

Feature Guides

  • DEMO_TRANSACTIONS.md 🍺₿ - Transaction tools reference

    • All 5 wallet tools explained
    • Usage examples and scenarios
    • API reference

  • CIRCULAR_ECONOMY.md 🔄 - Complete economy guide

    • USD → Crypto → Beer flow
    • Smart suggestions when insufficient balance
    • Inventory tracking
    • Fun challenges and scenarios

  • CHAT_WALLET_INTEGRATION.md 💬 - Chat integration

    • Using wallet tools in conversation
    • Visual transaction receipts
    • Example conversations

Setup & Configuration

Interactive Docs

✨ Recent Updates

🍺₿ Circular Economy (Latest!)

  • Buy virtual beer WITH cryptocurrency! - Complete USD→Crypto→Beer flow
  • Smart AI guidance - Suggests buying crypto if insufficient balance
  • Inventory tracking - See your beer collection in wallet
  • Transaction receipts - Beautiful visual feedback in chat
  • 13 total MCP tools - 8 market data + 5 transaction tools

🎤 Voice & AI Features

  • Multi-language voice input - Speak questions in 50+ languages (OpenAI Whisper)
  • Text-to-speech - Hear AI responses read aloud (OpenAI TTS)
  • GPT-4 integration - Intelligent conversations with tool orchestration
  • Visual tool indicators - See which MCP tools were used

💰 Virtual Wallet System

  • Demo transactions - Safe crypto purchase simulation
  • Beer calculator - Fun way to understand crypto value
  • Real-time pricing - Uses live Coinbase data
  • Transaction history - Track all purchases
  • Portfolio view - See all balances in one place

Chat Session Management

  • Persistent chat sessions across browser tabs
  • Session history with auto-titling
  • Real-time session switching
  • localStorage-based persistence
  • Observer pattern for live updates

API Explorer

  • Interactive testing for all 8 MCP tools
  • Real-time API responses
  • Code generation (cURL, JavaScript)
  • Copy-to-clipboard functionality
  • Comprehensive parameter documentation

Cursor MCP Integration

  • Pre-configured .cursor/mcp.json
  • Auto-loading of 8 MCP tools
  • Ready-to-use cryptocurrency queries
  • Professional development workflow

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📋 Roadmap

  • v1.0: Core MCP server with 8 tools
  • v1.1: Chat session persistence
  • v1.2: Interactive API explorer
  • v1.3: Cursor IDE integration
  • v1.4: WebSocket real-time streaming
  • v1.5: Advanced charting and technical indicators
  • v2.0: Multi-exchange support

🐛 Known Issues

  • Rate limiting on Coinbase public API (60 requests/hour for some endpoints)
  • Chat sessions limited to localStorage (10 sessions max for performance)
  • Client-side API keys should only be used in development

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Model Context Protocol team for the excellent specification
  • Coinbase for providing robust public APIs
  • Cursor for excellent MCP integration
  • The open-source community for invaluable tools and libraries

📞 Support

Made with ❤️ by Vladimir Bichev for the crypto and AI communities

Related Servers