# 🌌 Crypto MCP Server & Hedgehog Agentic Trading Dashboard 🦔

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

[![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)

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

```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://<PI_IP>: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://<pi-ip>: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.

<div align="center">
  <img src="https://raw.githubusercontent.com/PelleNybe/PelleNybe/main/assets/line.svg" width="100%" height="2" onerror="this.style.display='none'"/>
  <p><i>Stay Cypherpunk. Keep Building. ⚡</i></p>
</div>