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.

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.

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.

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

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

• 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)

• 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)

• 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