---

👨‍💻 Developer & Company

This project is brought to you by Pelle Nyberg and his company, Corax CoLAB.

---

📚 Table of contents

Click to expand/collapse contents

• 👨‍💻 Developer & Company
• 🌌 100% Real Data Integration & Visualizer Dynamics
• 🗺️ System Overview & Architecture
• ✅ Quick start — automated
• 🛠 Manual install
• ⚙️ Configuration
• 🔗 Claude Desktop integration
• 🖥 Dashboard user manual
• 🔒 Security & best practices

---

✨ 10 Technical and Visual Upgrades

1. Async Portfolio MCP: The portfolio_mcp.py now fetches concurrent exchange balances using ccxt.async_support for incredibly fast dashboard load times.
2. Robust Proxy Timeouts: The Node backend implements robust AbortSignal logic for MCP communication, preventing hanging connections.
3. SQLite Indices: The backend automatically initializes proper database indices on orders.db for created_at and status to dramatically speed up log querying.
4. WebSocket Resilience: The React frontend implements a centralized, self-healing Socket.io client ensuring the dashboard never goes stale if the backend restarts.
5. Strict Input Validation: Backend order execution endpoints rigorously validate symbol format, trade side, and order type before dispatching to the MCP.
6. Cyberpunk Loaders: Components like PortfolioPanel and TickerPanel feature animated, stylized loading states during data decryption.
7. Neon Toasts: A custom notification system provides sleek, auto-dismissing visual feedback for system events and order executions.
8. Enhanced Orders Table: The OrdersLogPanel is upgraded with pagination, neon-color-coded status badges, and interactive hover effects.
9. Glitch Effects: Critical data changes trigger subtle CSS glitch animations, enhancing the cyberpunk aesthetic.
10. Dynamic Theme Colors: The entire dashboard reacts to global market sentiment, shifting its neon glowing borders based on whether the market is bullish or bearish.

🌌 100% Real Data Integration & Visualizer Dynamics (Upgraded v3.0)

The Crypto MCP Server has been heavily upgraded to ensure every single conceptual placeholder has been actively replaced with real data mechanisms. The entire system operates without a single mockup across visualizers. All 3D graphs reflect live local data.

• 🎯 Dark Pool Sonar: Real-time 3D sonar pings for large volume "whale" trades on central exchanges. Connected to MCP_CCXT to monitor fetch_trades data and renders physics-based 3D ripples with @react-three/fiber.
• 🔥 Flash-Crash Prediction Matrix: Visualizes the ratio of bids to asks as a dynamic glowing heatmap grid, tracking potential liquidity drains using MCP_CCXT fetch_order_book.
• 🚀 Galaxy View (Gravity Well): Maps the top 50 cryptocurrencies in a 3D galaxy using MCP_COINGECKO. Star size = Market Cap, orbit speed = Volume, color = 24h change.
• 🧠 AI Sentiment Word-Cloud Sphere: Fetches recent crypto news via MCP_NEWS and extracts trending keywords and sentiment to form a 3D interactive floating word sphere.
• ⚡ Gas & Network Congestion Hologram: Visualizes current Ethereum network congestion as a glowing, pulsating reactor core using MCP_ONCHAIN gas_price. Faster pulsing/red colors indicate high congestion.

🏛 Legacy Visualizers

• Arbitrage Wormhole: Live Cross-DEX arbitrage detection using multi-exchange CCXT MCP polling.
• Neural Trade Visualizer: Calculates genuine diagnostic routing data retrieved from live orderbooks (L2 Bids/Asks) using react-three-fiber.
• Quantum Risk Map: Real-time 3D topography of your portfolio risk exposure.
• Orbital Portfolio Deck: A dynamic, physics-based 3D visualization of your actual asset allocation.
• Global Weather System: An interactive background system that reacts to the current market sentiment (Bull, Bear, Neutral), altering the entire visual environment.

---

🚀 The Multi-MCP Ecosystem

This repository has evolved into a Multi-MCP Hub - a Hedge Fund AI Orchestrator. The vision is that anyone downloading this repo can easily configure their AI agent to use our server for execution/raw data, combined with external public MCPs for analysis.

Synergy examples:

• Aarna ATARS: High-frequency sentiment signals and specialized DeFi analytics.
• Blockscout: Contract safety, verified smart contract readouts.
• LunarCrush: Social sentiment and trending metrics.
• Corax Crypto MCP (This repo): Trade execution, real-time monitoring, and local AI reasoning.

How to use the Multi-MCP Configuration

We provide a multi_mcp_config.example.json file that shows you how to connect your AI client (like Claude Desktop or Cursor) to multiple servers simultaneously.

1. Open your AI client's MCP configuration file.
   • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
   • Cursor: Add servers in Cursor Settings > Features > MCP.
2. Copy the structure from multi_mcp_config.example.json.
3. Fill in any required API keys (like LUNARCRUSH_API_KEY).
4. Restart your AI client.

This setup is completely hardware- and OS-agnostic. Use start_server.sh or Docker to run the local Corax Server seamlessly on any environment!

🤖 Autonomous Orchestrator Mode (Agentic Loop)

We are introducing Track 2: Agentic Orchestration, evolving the project from a passive Multi-MCP tool into an autonomous, 24/7 trading agent framework.

The autonomous_orchestrator.py script acts as an MCP Client, automatically connecting to the MCPs defined in your multi_mcp_config.example.json.

It runs a continuous Observe-Analyze-Act (OODA) loop:

1. Observe (gather_market_data): Queries Aarna ATARS for technical signals and LunarCrush for sentiment.
2. Analyze (analyze_with_llm): Evaluates signals using an LLM (e.g., Gemini or Claude) to return a structured decision (BUY, SELL, HOLD).
3. Act (execute_trade): If a trade is decided, it calls the local Corax MCP to execute the trade.

How to use the Autonomous Orchestrator

1. Ensure your API keys are set correctly in .env and your multi-MCP configuration.
2. You can test the orchestrator locally:

   python3 autonomous_orchestrator.py
   

3. Run 24/7 as a background service: We provide a systemd service template systemd/corax_orchestrator.service. Copy it to your systemd folder, enable it, and start it to let your AI daemon trade fully autonomously:

   sudo cp systemd/corax_orchestrator.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now corax_orchestrator.service
   

🗺️ System Overview & Architecture

The image series below illustrates the key stages of the Crypto MCP Server, bridging AI (Claude Desktop), local tools, and blockchain technology.

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:

# 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 to do everything yourself:

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
   

   sudo apt update
   sudo apt install -y curl build-essential ca-certificates git
   

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

---

🔗 Claude Desktop integration

Add MCP servers in Claude Desktop (step-by-step)

1. Open Claude Desktop app.
2. Open App Settings / Preferences.
3. Find Local MCP Servers.
4. Click + (Add) — fill fields one by one:
   • 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, notifier, llm, etc.) with their respective ports.

---

🖥 Dashboard user manual

• 📊 Portfolio: View aggregated balances & USD value (async fetching for speed).
• 📈 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 (backend requires execute:true).
• 📜 Orders log: Shows previews and executed orders (real-time updates via socket.io, paginated with indices).
• 🤖 AI Copilot: Voice-activated command center powered by real local LLMs.

⚠️ Safety: Always test with testnet keys. The UI requires confirmation to execute live orders.

---

🔒 Security & best practices

• Testnet First: Use testnet keys while testing.
• Environment Variables: Keep API keys out of repo — store them in the MCP server config or in secure .env not committed.
• Network Isolation: Restrict access to MCP endpoints to LAN only (UFW rules) or use VPN/SSH tunnels.
• Authentication: Auth bypass vulnerabilities via insecure req.ip validation on localhost have been successfully patched. /api/order/pending and /api/order/reasoning endpoints are now fully secured with DASHBOARD_PASSWORD verification.

🤖 Autonomous Orchestrator Mode

The Autonomous Orchestrator Mode evolves the project from a passive Multi-MCP tool into an autonomous, 24/7 trading agent framework. It features a "Board of Directors" consensus logic, Telegram Command Center, and an Agentic Backtesting Engine. It runs a continuous Observe-Orient-Decide-Act (OODA) loop, connecting to external MCPs like Aarna ATARS and LunarCrush to gather market signals, and then utilizes an LLM to analyze the data and make trading decisions. The local Corax MCP is then instructed to execute trades if necessary.

To enable and configure the orchestrator, you can simply edit your .env file to select the LLM "brain" of your choice without editing any Python logic:

# --- Autonomous Orchestrator Settings ---
# Choose your provider: 'gemini', 'anthropic', or 'openai'
ACTIVE_LLM_PROVIDER="gemini"

# API Keys for the LLM providers (only the active one is required)
GEMINI_API_KEY="your_google_gemini_key_here"
ANTHROPIC_API_KEY="your_claude_api_key_here"
OPENAI_API_KEY="your_openai_api_key_here"

Proof of Brain / Trading Diary

To provide full transparency, the Autonomous Orchestrator includes a "Proof of Brain" module. After every complete OODA cycle (Observe, Analyze, Act), a comprehensive Markdown report is generated in the trading_diary/ directory.

These reports document every decision made by the AI Board of Directors, answering why a specific action was taken. They include:

• The raw market data the orchestrator gathered from its MCPs.
• The individual votes and reasoning from the Technical Analyst (Gemini), Macro Strategist (OpenAI), and Risk Manager (Anthropic).
• The final consensus reached and execution parameters.

Reports are saved even if the board's decision is "HOLD", ensuring a fully auditable track record of the agent's logic.

Telegram Command Center

The Autonomous Orchestrator includes a built-in Telegram integration allowing you to receive real-time alerts and send commands to your trading agent.

1. Create a Bot: Talk to @BotFather on Telegram, create a new bot, and get the HTTP API Token.
2. Get Chat ID: Message your new bot, then go to https://api.telegram.org/bot<YourBOTToken>/getUpdates to find your chat_id.
3. Update .env:

   TELEGRAM_BOT_TOKEN="your_token_here"
   TELEGRAM_CHAT_ID="your_chat_id_here"
   TELEGRAM_NOTIFICATIONS_ENABLED="true"
   

Available Commands:

• /status - Returns the current active AI providers, the target ticker, and the last known decision.
• /report - Directly sends you the latest "Proof of Brain" markdown report as a document.
• /analyze - Manually triggers the agent to run an OODA cycle instantly without executing a trade.

Agentic Backtesting

To safely test the AI prompts and model configurations against past market behavior, we provide an Agentic Backtesting Engine. This allows you to simulate the "Board of Directors" consensus logic without risking real funds.

The backtest uses the ccxt library to fetch actual historical OHLCV data and simulates the market environment the orchestrator would have seen at that time.

To run a backtest:

python3 backtest_orchestrator.py

After the simulation finishes, a detailed markdown report summarizing the starting period, ending period, total simulated actions (BUYS, SELLS, HOLDS), and the AI's reasoning will be generated in the trading_diary/ directory (e.g., YYYYMMDD_HHMMSS_[TICKER]_BACKTEST.md).

A systemd/corax_orchestrator.service template is provided to run the autonomous_orchestrator.py script as a 24/7 background daemon on Linux.