Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/pellenybe/crypto-mcp-server---by-corax-colab

Crypto MCP Server by Corax CoLAB. Enables Claude to: Fetch prices (CoinGecko), Trade (CCXT), Get on-chain data, Perform TA, Aggregate portfolios, Send alerts, and Sync with Freqtrade via a cyberpunk 3D dashboard.
https://github.com/pellenybe/crypto-mcp-server---by-corax-colab

ccxt claude coingecko cryptocurrency freqtrade mcp rest-api

Last synced: 2 months ago
JSON representation

Crypto MCP Server by Corax CoLAB. Enables Claude to: Fetch prices (CoinGecko), Trade (CCXT), Get on-chain data, Perform TA, Aggregate portfolios, Send alerts, and Sync with Freqtrade via a cyberpunk 3D dashboard.

Awesome Lists containing this project

README 

          


  

    Frontend Dashboard

  



  
🌌 Crypto Multi-MCP Hub 
 by Corax CoLAB & PelleNybe 🚀🪙



  
Hedge Fund AI Orchestrator



  


    Typing SVG

  



  


    Version

    Python

    Node.js

    React

    Three.js

    License

  



  
The ultimate AI-driven command center and Multi-MCP Hub for your local crypto operations, featuring a dark, cyberpunk/command-center aesthetic. Built for everyone, from homebrew Raspberry Pi setups to cloud servers.





---



## 👨‍💻 Developer & Company





  






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






  

    

      

        
Pelle Nyberg


        
Lead Developer & Architect


        GitHub

        LinkedIn

        Portfolio

      

      

        
Corax CoLAB


        
Innovation & AI Solutions


        Website

        Crypto Dashboard

      

    

  






  




---



## 📚 Table of contents



  Click to expand/collapse contents

  



---



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

   ```bash

   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:

   ```bash

   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.





  Architectural Overview




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.





  Installation and Configuration




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.





  Security and Best Practices




---



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



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

   ```



   ```bash

   sudo apt update

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

   ```



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

```



---



## 🔗 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://: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.





  

  
Stay Cypherpunk. Keep Building. ⚡





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



```env

# --- 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/getUpdates` to find your `chat_id`.

3.  **Update `.env`:**

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

```bash

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.