🌌 Crypto MCP Server & Hedgehog Agentic Trading Dashboard 🦔

A Professional-Grade, Fully Localized AI Hedge Fund Orchestrator.

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 | Corax CoLAB 🎪 Explore more: Crypto P's Crypto Circus

<div align="center"> <img width="800" alt="Cyberpunk Crypto Dashboard" src="./gui/frontend/public/images/dashboard.jpg" style="border-radius: 12px; margin-bottom: 20px; border: 1px solid #333; box-shadow: 0 4px 15px rgba(0,255,150,0.1);" onerror="this.style.display='none'" /> </div>

🧬 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).
• 🧠 Oracle Copilot: Voice-activated command center powered by local LLMs via MCP_LLM.
• 🌍 Global Weather System: Dynamic 3D visualization of market volatility and network states using @react-three/fiber.
• 🌊 Whale Sonar Sweep & Constellations: 3D plotting of significant market movers using CoinGecko and CCXT data.
• 🌀 Arbitrage Wormhole: Scans and visualizes cross-exchange price discrepancies via MCP_CCXT.
• 📊 Risk Radar Panel & Quantum Risk Map: Spatial representation of portfolio risk, exposure, and technical analysis indicators (RSI, MACD) via MCP_TA.
• 📡 Market Sentiment Analyzer: Synthesizes news, price action, and LLM analysis for a comprehensive market mood score.
• 🔮 Predictive Ghosting: Overlays projected price actions based on historical patterns using plotly and MCP_TA.
• 🌐 Neural Net Liquidity & Trade Visualizer: 3D force-directed graphs showing the flow of liquidity and order execution.
• 🏗️ Algo Grid Architect: Node-based strategy builder and visualizer for algorithmic trading logic.
• 📈 Holo Order Flow & Topographic Order Book: Three-dimensional mapping of order book depth and flow.
• 🪐 Asset Universe & Orbital Portfolio: Represents portfolio holdings as a 3D solar system with relative distances and sizes.
• 📰 News Singularity: Aggregates and visually groups crypto news streams using MCP_NEWS.
• ⚡ Volatility Matrix: Visualizes standard deviations and market swings in a grid.
• 🖥️ System Overview: A comprehensive hub showing MCP node statuses and system health.

---

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

<details> <summary><b>🛠️ View Included MCPs (Click to expand)</b></summary> <br>

| MCP Server | Description | Port | | :--- | :--- | :--- | | 💱 ccxt_mcp | The core exchange trading & market data integration via CCXT. | 7001 | | ⛓️ onchain_mcp | ETH balances, ERC20 balances, transaction info, and live Gas Prices. | 7002 | | 📊 ta_mcp | Compute Technical Indicators (RSI, MACD, SMA50, BB) and Monte Carlo Simulations. | 7003 | | 💼 portfolio_mcp | Aggregated portfolio balances and performance tracking. | 7004 | | 🦎 coingecko_mcp | Deep market stats, top coins, and historical trends. | 7005 | | 🧠 llm_mcp | Local/Remote LLM operations and Copilot interactions. | 7006 | | 🔔 notifier_mcp | System notifications, alerts, and Telegram broadcasting. | 7007 | | 📈 freqtrade_mcp | Interfaces with local Freqtrade instances via REST APIs. | 7011 | | 🏟️ ha_mcp | Prediction markets for agents via HeadlineArena (financial and Civic Index). | 7018 | | 🐙 octobot_mcp | Interfaces with local OctoBot instances via REST APIs. | 7012 | | 🐦 hummingbot_mcp | Controls local Hummingbot Gateway APIs. | 7013 | | 🤖 superalgos_mcp | Interacts with the Superalgos platform API. | 7014 | | 📰 news_mcp | Fetches the latest crypto news from CryptoPanic. | 7017 |

</details>

---

🗺️ System Overview & Architecture

Explore the architecture, installation success, and security models below:

<details> <summary><b>1️⃣ Architectural Overview (Click to expand)</b></summary> <br> 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. <div align="center"> <img width="800" alt="Architectural Overview" src="./gui/frontend/public/images/architecture.jpg" style="border-radius: 12px; margin-bottom: 20px; border: 1px solid #333; box-shadow: 0 4px 15px rgba(0,255,150,0.1);" onerror="this.style.display='none'" /> </div>

📸 [INSERT LATEST GUI SCREENSHOT HERE] (Please upload the latest working system screenshot or animation here)

</details> <details> <summary><b>2️⃣ Installation and Configuration (Click to expand)</b></summary> <br> The terminal displays successful execution steps of the automated `install.sh` script, automating directory creation, Node.js installation, and service setup. <div align="center"> <img width="800" alt="Installation and Configuration" src="./gui/frontend/public/images/installation.jpg" style="border-radius: 12px; margin-bottom: 20px; border: 1px solid #333; box-shadow: 0 4px 15px rgba(0,255,150,0.1);" onerror="this.style.display='none'" /> </div> </details> <details> <summary><b>3️⃣ Security and Best Practices (Click to expand)</b></summary> <br> Summarizes the core security principles: using testnet keys, securing API keys, restricting network access, leveraging local control, and implementing an authenticated reverse proxy. <div align="center"> <img width="800" alt="Security and Best Practices" src="./gui/frontend/public/images/security.jpg" style="border-radius: 12px; margin-bottom: 20px; border: 1px solid #333; box-shadow: 0 4px 15px rgba(0,255,150,0.1);" onerror="this.style.display='none'" /> </div> </details>

---

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

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

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:

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

curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

3. Backend & Global Config:

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

cd $HOME/cryptomcpserver/gui/frontend
npm install
npm run dev -- --host   # Open http://<PI_IP>:5173 on your laptop

5. Systemd (Backend):

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

# 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