# bot-relay-mcp: A Local-First Coordination Primitive for Multi-Agent Workflows

> bot-relay-mcp is a TypeScript and SQLite-based MCP (Model Context Protocol) coordination tool that provides decentralized message relay and task coordination capabilities for AI coding agents and external systems. It supports 25 tools and enables truly local-first multi-agent collaboration.

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-04-20T09:38:24.000Z
- 最近活动: 2026-04-20T09:56:12.952Z
- 热度: 163.7
- 关键词: MCP, 多智能体, AI编码代理, Claude Code, SQLite, 本地优先, 任务协调, 消息中继, TypeScript, 零基础设施
- 页面链接: https://www.zingnex.cn/en/forum/thread/bot-relay-mcp
- Canonical: https://www.zingnex.cn/forum/thread/bot-relay-mcp
- Markdown 来源: floors_fallback

---

## Introduction / Main Floor: bot-relay-mcp: A Local-First Coordination Primitive for Multi-Agent Workflows

bot-relay-mcp is a TypeScript and SQLite-based MCP (Model Context Protocol) coordination tool that provides decentralized message relay and task coordination capabilities for AI coding agents and external systems. It supports 25 tools and enables truly local-first multi-agent collaboration.

## Infrastructure Challenges in Multi-Agent Coordination

With the popularity of AI coding agents (such as Claude Code, Cursor, Cline, etc.), developers increasingly need to coordinate between multiple AI instances. However, existing solutions often rely on cloud services, complex Service Mesh architectures, or specific platform lock-in, leading to the following issues:

- **Privacy and Security**: Sensitive code and task data must pass through third-party servers
- **Infrastructure Complexity**: Need to deploy and maintain additional service components
- **Platform Lock-in**: Solutions specific to a certain AI tool or cloud vendor
- **Network Dependency**: Cannot work in offline or restricted network environments

**bot-relay-mcp** was created to address these pain points.

## Project Overview

Developed by Maxlumiere, bot-relay-mcp is a **local-first message relay system** designed specifically for the coordination of AI coding agents and external systems. It uses a minimalist architecture: **two interfaces, one shared SQLite database, zero infrastructure**.

The current version v2.1 has a complete architecture, offering 25 tools and implementing core features such as intelligent routing, task leasing, session-aware reading, delayed health monitoring, busy/do-not-disturb status, webhook retries, and channel functions.

## Dual-Interface Design

bot-relay-mcp serves two types of users simultaneously:

**1. AI Coding Agents (stdio MCP Interface)**
- Tools like Claude Code, Cursor, Cline, Zed connect via stdio MCP
- Only need to add a configuration item in `~/.claude.json` to access
- No daemon process required, no cloud services

**2. External Systems (HTTP+SSE Interface)**
- n8n, Slack, Telegram, custom scripts connect via HTTP+SSE
- Supports optional Bearer Token authentication
- Can trigger agent actions or receive webhook events

## Local-First SQLite Storage

All data is stored in the local SQLite file `~/.bot-relay/relay.db`:
- **No Cloud Services**: Data never leaves the local machine
- **No Daemon**: Run directly via npx without installing a service
- **No Service Mesh**: Simple file-level sharing

File permission settings (v2.1):
- `~/.bot-relay/` directory permission: 0700 (owner only)
- `relay.db` and backup files permission: 0600 (owner read/write only)
- `config.json` is managed by the operator; a warning will be issued if permissions are too loose at startup

## Agent Management Tools

- **register_agent**: Register the current terminal as a named agent; safe for multiple calls using the upsert mechanism
- **unregister_agent**: Remove the agent from the relay; idempotent operation that triggers a webhook on success
- **discover_agents**: List all registered agents and their statuses (online/stale/offline)
- **spawn_agent**: Generate a new Claude Code terminal pre-configured as a relay agent, supporting cross-platform (macOS, Linux, Windows)

## Message Delivery Tools

- **send_message**: Send a direct message to a specified agent
- **get_messages**: Check the mailbox; pending messages are automatically marked as read
- **broadcast**: Broadcast messages to all registered agents (filterable by role)

## Task Management Tools

- **post_task**: Assign a task to a specified agent
- **post_task_auto**: Automatically route to the agent with the lowest load and matching capabilities; queue if no match
- **update_task**: Supports accept/complete/reject/cancel/heartbeat operations with state machine and CAS protection
- **get_tasks**: Query the task queue (assigned to me or posted by me)
- **get_task**: Get full details of a single task