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?
| Component | Status | Source |
|---|---|---|
| 💰 Cryptocurrency Prices | ✅ Real | Coinbase Public API |
| 📊 Market Statistics | ✅ Real | Coinbase Public API |
| 📈 Historical Data | ✅ Real | Coinbase Public API |
| 🤖 GPT-4 AI Chat | ✅ Real | OpenAI |
| 🎤 Voice Input (Whisper) | ✅ Real | OpenAI |
| 🔊 Text-to-Speech | ✅ Real | OpenAI |
| 🔌 MCP Protocol | ✅ Real | Official SDK |
| 💵 Wallet Balances | 🎮 Simulated | In-memory demo |
| 💸 Transactions | 🎮 Simulated | Educational only |
| 🍺 Beer Purchases | 🎮 Simulated | Virtual 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
-
Clone the repository
git clone https://github.com/your-username/coinbase-chat-mcp.git cd coinbase-chat-mcp -
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 .. -
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 .. -
Build the MCP server
cd mcp-server npm run build cd .. -
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:
- Automatic Configuration -
.cursor/mcp.jsonis already configured - Restart Cursor - MCP server will auto-load with 8 tools available
- 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)
- get_spot_price - Current cryptocurrency prices
- get_historical_prices - Historical price data with time ranges
- get_exchange_rates - Fiat currency exchange rates
- search_assets - Find cryptocurrencies and assets
- get_asset_details - Detailed asset information
- get_market_stats - 24-hour market statistics
- get_popular_pairs - Popular trading pairs
- analyze_price_data - Technical analysis (volatility, trends, support/resistance)
🍺₿ Demo Transaction Tools (5) - NEW!
- calculate_beer_cost - Convert beer money to crypto amounts
- simulate_btc_purchase - Simulate buying crypto with USD
- buy_virtual_beer 🔥 - Buy virtual beer WITH crypto! (Circular economy)
- get_virtual_wallet - View demo wallet balance and stats
- 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:
- Get OpenAI API Key: Visit OpenAI Platform
- Create frontend/.env file:
VITE_OPENAI_API_KEY=sk-your-actual-api-key-here - 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
- 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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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