# 🌌 Crypto MCP Server & Hedgehog Agentic Trading Dashboard 🦔 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![Node.js 20+](https://img.shields.io/badge/node-20+-brightgreen.svg)](https://nodejs.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) A massively scaled **Model Context Protocol (MCP)** infrastructure designed to act as a localized, AI-powered Hedge Fund Orchestrator. It acts as the backbone for local LLMs (like Claude Desktop) to ingest real-time market data, analyze technicals/sentiment, and autonomously execute trades. > 🌟 **Author:** [Pelle Nyberg](https://github.com/PelleNybe) | [Corax CoLAB](https://coraxcolab.com) > 🎪 **Explore more:** [Crypto P's Crypto Circus](https://cryptop.coraxcolab.com)

## 🧬 What makes this different? This is not just another API wrapper. It is a **multi-agent architectural playground**. * **Zero Mock-ups. 100% Real Data.** Every visualizer, sonar sweep, and grid is driven by live websockets and REST data. * **Extensible MCP Architecture.** Easily add new modules. The system natively multiplexes JSON-RPC commands. * **Hardened Security.** Local SQLite, password-protected backend execution, no cross-site scripting gaps. Uses `crypto.timingSafeEqual` for password verification. Our terminal is a living, breathing **Hedge Fund AI Orchestrator**, packed with cutting-edge tools. ### 🤖 Autonomous Orchestrator Mode (Agentic Loop) Evolving from a passive Multi-MCP tool, the server acts as an autonomous **24/7 trading agent framework** running a continuous **Observe-Analyze-Act (OODA)** loop. * 👁️ **Observe (`gather_market_data`)**: Queries multiple MCPs (e.g., Technical indicators, News sentiment, On-chain data). * 🧠 **Analyze (`analyze_with_llm`)**: Evaluates signals using an LLM (Gemini, Claude, or OpenAI) for a structured decision (**BUY, SELL, HOLD**). * ⚡ **Act (`execute_trade`)**: Executes trades via the local CCXT MCP. * 🧪 **Agentic Backtesting**: Safely test AI prompts and models against historical OHLCV data without risking real funds. * 📖 **Proof of Brain (Trading Diary)**: Comprehensive markdown reports detailing the "Board of Directors" reasoning for every action taken. ### 📱 Telegram Command Center Receive real-time alerts and command your trading agent via Telegram. * **`/status`**: View active AI providers and last decisions. * **`/report`**: Receive your latest "Proof of Brain" report. * **`/analyze`**: Trigger a manual OODA cycle. ### 🌌 100% Real Data Integration & Visualizer Dynamics The Crypto MCP Server uses **real data** across all visualizers. The entire system operates without a single mockup! * 🎯 **Dark Pool Sonar:** Real-time 3D sonar pings for large volume "whale" trades on central exchanges using `@react-three/fiber` and dynamic emissive materials. * 🔥 **Flash-Crash Prediction Matrix:** Glowing heatmap grid of bids to asks, tracking liquidity drains in real time via CCXT orderbooks. * 🚀 **Galaxy View (Gravity Well):** Cinematic 3D mapping of the top 50 cryptocurrencies with a glowing central sun and accretion disk. * 🧠 **AI Sentiment Word-Cloud Sphere:** Extracts trending keywords and sentiment from real-time news to form an interactive 3D floating sphere. * ⚡ **Gas & Network Congestion Hologram:** Visualizes Ethereum network congestion as a glowing, pulsating reactor core. * 🔬 **Time-Machine Backtest Arena:** Fully functional OHLCV visualizer to playback and simulate trading strategies (e.g. SMA Crossovers). --- ## 🚀 The Multi-MCP Ecosystem This repository comes bundled with over a dozen powerful **MCPs (Model Context Protocol)**. They provide execution, raw data, analysis, and external system integrations.

🛠️ View Included MCPs (Click to expand)

--- ## 🗺️ System Overview & Architecture Explore the architecture, installation success, and security models below:

1️⃣ Architectural Overview (Click to expand)

Claude Desktop communicates via JSON-RPC with the Crypto MCP Server backend (REST + WebSocket). The server acts as a proxy, directing traffic to specific local MCP tools—such as CCXT, CoinGecko, and Portfolio—while logging orders to a local SQLite database.

2️⃣ Installation and Configuration (Click to expand)

The terminal displays successful execution steps of the automated `install.sh` script, automating directory creation, Node.js installation, and service setup.

3️⃣ Security and Best Practices (Click to expand)

Summarizes the core security principles: using testnet keys, securing API keys, restricting network access, leveraging local control, and implementing an authenticated reverse proxy.

--- ## ✅ Quick Start — Automated Place the provided `install.sh` into `$HOME/install.sh` (or `$HOME/cryptomcpserver/install.sh` if you prefer). Make it executable and run it: ```bash # Save install.sh to $HOME/install.sh, then: cd $HOME chmod +x install.sh ./install.sh ``` **What `install.sh` does (summary):** 1. Creates directories and writes backend & frontend files. 2. Installs Node.js if missing and runs `npm install` for backend & frontend. 3. Ensures the `orders` table exists in `$HOME/cryptomcpserver/gui/backend/orders.db`. 4. Frees port `4000` if occupied, then installs & enables the systemd service `crypto-mcp-gui.service`. 5. Attempts a production build of the frontend. > **After running, check service status and logs:** ```bash sudo systemctl status crypto-mcp-gui.service sudo journalctl -u crypto-mcp-gui.service -f ``` --- ## 🛠 Manual Install If you prefer a hands-on approach: **1. Install system deps & Python Requirements:** ```bash sudo apt update sudo apt install -y curl build-essential ca-certificates git python3-pip pip3 install -r requirements.txt ``` **2. Install Node.js (if needed):** ```bash curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs ``` **3. Backend & Global Config:** ```bash cd $HOME/cryptomcpserver cp .env.example .env # Edit .env to add your passwords, keys, and allowed pairs cd gui/backend npm install ``` **4. Frontend (Dev):** ```bash cd $HOME/cryptomcpserver/gui/frontend npm install npm run dev -- --host # Open http://:5173 on your laptop ``` **5. Systemd (Backend):** ```bash # Create /etc/systemd/system/crypto-mcp-gui.service sudo systemctl daemon-reload sudo systemctl enable --now crypto-mcp-gui.service ``` --- ## ⚙️ Configuration The system uses a centralized `.env` file located at the root of the project to manage both Python MCP servers and the Node.js backend. Copy and edit `$HOME/cryptomcpserver/.env.example` → `.env`: ```env # Essential configuration PORT=4000 DASHBOARD_PASSWORD=your_secure_password # Required for trading and AI reasoning ALLOWED_PAIRS=BTC/USDT,SOL/USDT # Fail-closed security: only these pairs are allowed MAX_TRADE_USD=100.0 # Maximum allowed trade amount per transaction # API Keys BINANCE_API_KEY=your_key BINANCE_API_SECRET=your_secret # --- Autonomous Orchestrator Settings --- ACTIVE_LLM_PROVIDER="gemini" GEMINI_API_KEY="your_google_gemini_key_here" TELEGRAM_BOT_TOKEN="your_token_here" TELEGRAM_CHAT_ID="your_chat_id_here" ``` --- ## 🔗 Claude Desktop Integration ### Add MCP servers in Claude Desktop (Step-by-step) 1. Open the **Claude Desktop** app. 2. Navigate to **App Settings / Preferences**. 3. Find **Local MCP Servers**. 4. Click `+` (Add) and fill in the fields: * **Name:** `ccxt` * **Description:** `CCXT MCP – exchange trading & market data` * **Transport:** `http` * **Endpoint:** `http://127.0.0.1:7001/mcp` (if Claude runs on Pi) or `http://:7001/mcp` (if Claude runs on laptop) 5. **Save**. Repeat for other MCPs (`coingecko`, `portfolio`, `onchain`, `ta`, `news`, etc.) using their respective ports. --- ## 🖥 Dashboard User Manual * 📊 **Portfolio:** View aggregated balances & USD value. * 📈 **Ticker:** Live market data (via `ccxt` MCP). * 🛒 **Order / Trade:** * **Preview (`dry_run`):** Calculates estimated cost and logs a preview. * **Confirm → Place order:** Sends `create_order` to CCXT MCP. * 📜 **Orders Log:** Real-time updates via Socket.io, paginated with indices. * 🤖 **AI Copilot:** Voice-activated command center powered by local LLMs. > ⚠️ **Safety Warning:** Always test with testnet keys. The UI requires confirmation to execute live orders. --- ## 🔒 Security & Best Practices * 🧪 **Testnet First:** Use testnet keys while testing your strategies. * 🔑 **Environment Variables:** Keep API keys absolutely out of the repository. * 🛡️ **Network Isolation:** Restrict access to MCP endpoints to your local LAN only. * 🔐 **Authentication:** Endpoints are fully secured with `DASHBOARD_PASSWORD` verification and robust anti-SSRF checks.

Stay Cypherpunk. Keep Building. ⚡