MCP Relay

A lightweight multi-client message bus that moves data between Claude Desktop and Claude Code without sharing context.

python

3

GitHub Stars

python

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "mhcoen-mcp-relay": {
      "command": "uvx",
      "args": [
        "mcp-server-relay",
        "--client",
        "desktop",
        "--sound"
      ]
    }
  }
}

The MCP Relay is a lightweight message bus that connects Claude Desktop and Claude Code, allowing you to send and fetch messages between them without mixing their contexts. It keeps your conversations separate while enabling you to share relevant data, configurations, and feedback on demand, improving collaboration between planning and execution workflows.

How to use

You interact with the relay mainly by sending a message to fetch or transmit information between Claude Desktop and Claude Code. From either side, you can trigger fetches to retrieve messages from the other side, or you can instruct the system to send a specific item. When a message arrives, you receive a system notification so you can decide when to read it.

How to install

Prerequisites depend on the installation path you choose. You will either use the uvx-based runtime to run a local MCP Relay server or clone the repository and run a Python-based server locally.

Option A: Using uvx (recommended for quick setup)

Ensure you have uvx installed on your system. If you do not have uvx, install it using the provided installer script.
Configure Claude Desktop to run the relay client in desktop mode
Configure Claude Code to run the relay client in code mode
Install the command and startup hook to enable the /get command and pending message previews on startup

Option B: Cloning the repository and running locally (Python)

Clone the repository and create a Python virtual environment
Install the package in editable mode
Run the relay server with the appropriate client flag, either desktop or code
Update your Claude Desktop and Claude Code configs to point at the local relay server using the full Python path and relay_server.py script

Additional setup notes

If you switch projects, the relay buffer remains accessible across projects. You can clear messages in the relay to start fresh. Large files travel slower through the relay, so prefer direct transfer for big payloads, while still using the relay for contextual notes.

Configuration and runtime behavior

The relay is designed to be simple and explicit. It behaves as a message bus for sending and fetching, without attempting to interpret or summarize content. You control when messages are fetched and when new messages are sent.

Security and privacy notes

Messages pass through a local relay store and are not automatically synchronized in the background. You control every fetch and send action, reducing unintended information leakage through uncontrolled background activity.

Examples and practical workflows

Example: You notice a bug in Code and want feedback from Desktop. You send a request to Desktop via the relay for the latest error messages. Desktop fetches the message, evaluates the error, and sends back updated guidance. You fetch again to read the plan.

Tools and capabilities

The relay exposes a small set of core tools to manage message flow between the two clients. Each tool is purpose-built to perform a specific action within the relay system.

Design and behavior notes

This solution emphasizes transport over memory. It does not create or share hidden context, nor does it perform cross-agent planning. Messages move through the relay as-is, and you initiate reads and writes to maintain clear boundaries.

Troubleshooting

If you do not see system notifications after sending a message, verify that the relay service is running and that the appropriate client (desktop or code) is configured. If messages seem stuck, use the clear command to reset the buffer and reinitialize the chat flow.

Notes on deployment and scalability

The relay supports multiple Code sessions connecting to the same Desktop instance. It is designed for local environments and can be extended with additional observers or backends if needed.

Available tools

relay_send

Send a message to the other side from either Desktop or Code, enabling cross-side communication.

relay_fetch

Fetch recent messages from the other side, with optional limits and unread filtering.

relay_clear

Clear all messages from the relay buffer to reset the conversation state.