Coinbase Chat MCP

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?

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):

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!

9. calculate_beer_cost - Convert beer money to crypto amounts

10. simulate_btc_purchase - Simulate buying crypto with USD

11. buy_virtual_beer 🔥 - Buy virtual beer WITH crypto! (Circular economy)

12. get_virtual_wallet - View demo wallet balance and stats

13. 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

📖 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

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:

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

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

🛠️ 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

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

• MCP_SETUP_NOTES.md - MCP integration guide for Cursor/Claude

• DEPLOYMENT.md - Deployment instructions

• CONTRIBUTING.md - Development contribution guidelines

Interactive Docs

• API Explorer - Interactive API testing (when running)

• Swagger UI - REST API documentation (when running)

✨ 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

• 🐛 Bug Reports: GitHub Issues

• 💬 Discussions: GitHub Discussions

• 📧 Questions: Create an issue with the "question" label

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