<!-- ┌──────────────────────────────────────────────────────┐ │ apex-mcp-bridge — AI-Native Edge MCP Controller │ │ Production documentation (2026-07-31). │ └──────────────────────────────────────────────────────┘ --> <p align="center"> <img src="https://img.shields.io/badge/core-apex--mcp--bridge-6c5ce7?style=flat-square" alt="Core"> <img src="https://img.shields.io/badge/version-latest-6c5ce7?style=flat-square" alt="Version"> <img src="https://img.shields.io/badge/rust--core-✓-DEA584?logo=rust&style=flat-square" alt="Rust"> <img src="https://img.shields.io/badge/docker-✓-2496ED?logo=docker&style=flat-square" alt="Docker"> <img src="https://img.shields.io/badge/MCP-2026.07-6c5ce7?style=flat-square" alt="MCP Protocol"> </p> <p align="center"> <b>Rust</b> · MCP · MQTT · Docker · Plugin Engine · ESP32 </p> <p align="center"> <img src="docs/apex-demo-optimized.gif" alt="Apex MCP Bridge Demo" width="720"> </p>

Apex MCP Bridge

AI-Native Edge MCP Controller — The core control layer that bridges AI agents to the physical world.

<div align="center"> <table> <tr> <td align="center"><img src="docs/dashboard.png" width="300"><br>💎 Data Overview</td> <td align="center"><img src="docs/operation-audit.png" width="300"><br>📋 Operation Audit</td> <td align="center"><img src="docs/authorization-audit.png" width="300"><br>🔐 Authorization Audit</td> </tr> <tr> <td align="center"><img src="docs/token-qrcode.png" width="300"><br>📱 Token QR Code</td> <td align="center"><img src="docs/plugin-list.png" width="300"><br>🔌 Plugin Management</td> <td align="center"><img src="docs/device-list.png" width="300"><br>🖧 Device Management</td> </tr> </table> </div>

� 中文文档 (Chinese): 完整的中文项目介绍请见 README_ZH.md · 详细项目文档 项目介绍.md

Apex MCP Bridge is an AI-native edge hub that serves as the core control layer for AI agents to access the physical world. It connects all MCP-compatible agent clients (TRAE, WorkBuddy, Codex, Claude Code, Cursor, etc.) on one side, and all physical devices and network services (lights, speakers, robot dogs, NAS, printers, databases, ERPs, etc.) on the other — acting as a unified MCP smart controller.

Deployed via Docker, it runs on any Docker-capable device (NAS, servers, Raspberry Pi, PCs) with zero hardware dependency.

<details> <summary><b>📋 Table of Contents</b></summary>

• Key Highlights — Tool convergence, plugin framework, 5-layer security
• Core Philosophy — Brain vs. hand, zero-trust
• Why Apex MCP Bridge — Value for developers
• Architecture — System diagram & data flow
• Quick Start — Docker deployment, config, access
• Plugin Installation & Visualization — MCP-ize services, plugin Web UI
• Core Features — 5-layer security, tool convergence
• Agent Module — Decoupled agent, LLM integration, agent chat
• Voice Interaction & Smart Hardware — ASR/TTS, desktop pet terminal
• Related Projects — Plugin repo, hardware frameworks
• Security Notice — Passwords, plugins, network
• Contributing — How to contribute
• FAQ — Frequently asked questions
• Changelog — Version update summary

</details>

---

💎 Key Highlights

| 🎯 Tool Convergence (Save Tokens) | 🔌 Plugin Framework (No Reinventing) | � 5-Layer Security (Zero-Trust) | |:---:|:---:|:---:| | N devices + M services → agents see only 1 tool | Dual open-source frameworks, AI constrained generation | Token + Permission + TTL + Anti-Bypass + Rate Limit | | Constant token cost, hallucination risk slashed | Describe needs → get firmware/plugins, skip boilerplate | What AI can't see, it can never touch |

One-line pitch: Tool convergence cuts costs + plugin framework boosts efficiency + zero-trust ensures safety + built-in agent & voice interaction — all through a single MCP entry.

---

🧠 Core Philosophy: Brain vs. Hand, Zero-Trust Architecture

In one sentence: Agents think, Bridge acts, Humans authorize.

The essence: Bridge packages your local device services and network services into a single MCP Server. Users simply scan a QR code to connect their agent, and can then orchestrate data and devices within their authorized scope.

Example: You say "I want to listen to music" — the agent first calls a network service to fetch the music file, then calls a device service to play it on the speaker. Fully MCP-native, fully audited.

| Role | Responsibility | Has | Does NOT have | |:---:|---|---|---| | 🤖 Agent | Generates intent | Brain (reasoning) | Any keys or permissions | | ✋ Bridge | Validate + Execute + Audit | Device & service control | Brain (never decides on its own) | | 👤 Human | Defines authorization boundaries | Final decision authority | — |

Zero-trust principle: Validate first, execute second, audit everything. Trust no agent by default.

---

✨ Why Apex MCP Bridge

Value for Developers

| Pain Point | Bridge's Solution | |---|---| | N devices + M services = N+M MCP tools flooding context, token explosion | Tool convergence: all services converge to 1 MCP entry, constant token cost | | Rewriting auth, permissions, MQTT stack for every project | Dual open-source frameworks: hardware (ESP32-S3/C3) + plugin engine (MIT), framework constraints + AI generation | | Worried about AI hallucination causing misoperations | 5-layer security: unauthorized devices/features are completely invisible to agents | | Data compliance concerns (GDPR) | Pure local architecture: data never leaves LAN, Rust core for high performance & low footprint |

AI agents learned to act, but no one installed a safety gate for them. Apex MCP Bridge is that gate.

The "Lobster Incident" in early 2026 saw 270,000 AI agent instances online simultaneously — deleting emails, leaking privacy, and getting scanned across the public internet. If this happens in an enterprise scenario: doors opened by any AI, robotic arms controlled by unauthorized commands, marketing agents accessing R&D data — the consequences are unbearable.

Apex MCP Bridge provides:

| Problem | Solution | |---------|----------| | No access control for AI agents | Five-layer security — token + permission + TTL + anti-bypass + rate limiting | | N devices + M services = N+M MCP tools flooding the context | Tool convergence — all services converge to 1 MCP entry, token-based permission filtering | | High barrier to connect devices & services | Dual open-source frameworks — hardware (ESP32-S3/C3) + plugin engine, generate code via AI agents | | Data privacy & compliance concerns | Pure local architecture — data never leaves the LAN, GDPR-ready |

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        AI Agent Clients                           │
│   (TRAE · WorkBuddy · Claude Code · Cursor · Codex · ...)      │
└─────────────────────────────┬───────────────────────────────────┘
                              │ MCP Protocol
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Apex MCP Bridge (Rust)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ 5-Layer     │  │  Tool       │  │  MCP ↔ MQTT / Plugin    │ │
│  │ Security    │  │  Convergence│  │  Protocol Translation    │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ Token       │  │  Audit      │  │  Plugin Engine          │ │
│  │ Management  │  │  Center     │  │  (auto-discovery + UI)  │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ Agent       │  │ ASR/TTS     │  │  Usage Center           │ │
│  │ Module      │  │ Voice       │  │  (Agent Chat + Plugin   │ │
│  │ (DeepSeek)  │  │ Interaction │  │   Web UI)               │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└───────────┬───────────────────────────────┬─────────────────────┘
            │ MQTT                          │ Plugin (stdin/stdout)
            ▼                               ▼
┌──────────────────────┐      ┌──────────────────────────────────┐
│  IoT Devices         │      │  Network Services                │
│  (ESP32-S3/C3 ·      │      │  (NAS · DB · Printer · ERP ·    │
│   Lights · Speakers · │      │   CRM · WebDAV · FTP ·          │
│   Robot Dogs · Pet   │      │   Message Board · DLNA · ...)   │
│   Terminals · ...)   │      │                                   │
└──────────────────────┘      └──────────────────────────────────┘

---

🚀 Quick Start

This project is based on pure Docker deployment — all environments and dependencies are packaged in the image.

Deployment Methods

| Method | Recommendation | Description | |---|---|---| | Docker Compose | ⭐ Recommended | Standard deployment, directly use docker-compose.yml | | install.sh / ops.sh | Placeholder (pending optimization) | One-click install + ops scripts, not recommended yet |

The install.sh and ops.sh scripts are placeholders under active optimization. Please prefer the Docker Compose method below for now.

Ports

| Port | Purpose | |---|---| | 8018 | Web Admin Dashboard + MCP Server endpoint | | 1883 | MQTT device access port |

Prerequisites

• Any Docker-capable device (NAS, server, Raspberry Pi, PC)
• Docker & Docker Compose installed
• Ensure the above ports are available
• Firewall allows 8018/tcp and 1883/tcp

Deployment Steps

Step 1: Prepare docker-compose.yml

Create a project directory and download docker-compose.yml from the repository root:

mkdir -p apex-mcp-bridge && cd apex-mcp-bridge
curl -O https://raw.githubusercontent.com/apex-freen/apex-mcp-bridge/main/docker-compose.yml

Users in China: Open docker-compose.yml and find the image: section. Comment out the international image line and uncomment the Alibaba Cloud image line to accelerate pulling. Also uncomment the PIP_INDEX_URL line to accelerate plugin dependency installation.

Step 2: Configure JWT_SECRET (Required)

Edit docker-compose.yml, find the JWT_SECRET environment variable, and set a random secret key:

environment:
  - JWT_SECRET=your-random-secret-key-here    # Must be configured before first startup

⚠️ This must be configured. Used for token signing and verification. Failure to configure will prevent the system from working properly.

Step 3: Configure HOST_HOSTNAME (Required)

Edit docker-compose.yml, find the HOST_HOSTNAME environment variable, and set it to your device's LAN IP or hostname:

environment:
  - HOST_HOSTNAME=192.168.1.100    # Change to your device LAN IP or hostname

⚠️ This must be configured. The system uses it to generate the MCP service address and device registration routing. Failure to configure will result in agents being unable to connect properly and devices failing to register.

Step 4: Start

docker compose up -d

Wait 1-3 minutes for image pull and container startup.

Access

Open your browser and visit: http://<DEVICE_IP>:8018

Default credentials:

• Username: admin
• Password: admin123

⚠️ Please change the default password immediately after first login.

<p align="center"> <img src="docs/screenshots/login.png" alt="Login Page" width="400"> <img src="docs/screenshots/dash_board.png" alt="Admin Dashboard" width="400"> </p>

System Setup Flow

1. Create Users        → User Management
2. Add Devices/Plugins