MCP Relay

🚀 Relay

Relay is a remarkably simple tool designed to transfer information, including files, code, data, comments, and directions, between Claude Desktop and Claude Code. It does so while keeping their main context windows separate, ensuring a smooth and efficient workflow.

Both Claude Desktop and Claude Code can send messages independently. When they require input from the other side, they initiate the process automatically. You'll receive a system notification upon the arrival of new messages, allowing you to retrieve them at your convenience.

Why is this useful? Claude Desktop and Claude Code each have their own strengths. Desktop excels in conversation-based tasks such as planning, brainstorming, reviewing, and refining prose. On the other hand, Code is better suited for execution, including editing files, running commands, and troubleshooting errors. However, they do not share context. Without Relay, if you draft something in Desktop and wish to implement it in Code, or if you seek Desktop's feedback on your code, you'd have to resort to copy - pasting between the two applications.

Relay bridges this gap without the need for you to manually formulate questions or perform cut - and - paste operations between windows. This is a fundamental functionality that should have been integrated by Anthropic.

You're in control. Retrieving messages is typically a user - initiated action. You can type get or /get to fetch messages. While the models can send or retrieve messages when they determine they need input from the other side, there is no automatic background synchronization. This prevents uncontrolled inter - LLM conversations that could consume your tokens.

🚀 Quick Start

✨ Features

• Seamlessly transfers information between Claude Desktop and Claude Code.
• Allows autonomous message sending by both Claude applications.
• Provides system notifications for new messages.
• User - controlled message retrieval to prevent token over - consumption.

📦 Installation

There are two ways to install Relay:

Using uvx

uvx enables you to run Python packages directly without global installation and handles dependencies automatically. If you don't have it, install it with the following command:

curl -LsSf https://astral.sh/uv/install.sh | sh

(See astral.sh/uv for more information.)

Configure Claude Desktop: Add the following to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop and instruct it to remember the following:

Remember: When the user says "get" or "/get" alone, fetch recent messages from the relay using relay_fetch.

You can verify the recording by saying "Show me my memory edits."

Configure Claude Code: Add the following to .mcp.json in your project root:

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

Note: Only Desktop needs --sound as it manages notifications for both sides.

Install the /get slash command (optional):

uvx mcp-server-relay --setup-code

This copies the slash command to ~/.claude/commands/.

Install from GitHub

If you prefer not to use uvx, you can clone the repository and run it directly:

git clone https://github.com/mhcoen/mcp-relay.git
cd mcp-relay
python -m venv .venv
.venv/bin/pip install -e .

Then use the full path in your configs:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "relay": {
      "command": "/path/to/mcp-relay/.venv/bin/python",
      "args": ["/path/to/mcp-relay/relay_server.py", "--client", "desktop", "--sound"]
    }
  }
}

Claude Code (.mcp.json):

{
  "mcpServers": {
    "relay": {
      "command": "/path/to/mcp-relay/.venv/bin/python",
      "args": ["/path/to/mcp-relay/relay_server.py", "--client", "code"]
    }
  }
}

Replace /path/to/mcp-relay with your actual clone location.

💻 Usage Examples

Basic Usage

[In Desktop]
You:     Send my last error message to Code.
Desktop: [sends via relay]

[notification pops up in Code's terminal]

[In Code]
You:     /get
Code:    Got it. That's from line 47 in parser.py—the regex isn't matching.
         [fixes the bug]

Advanced Usage

[In Code]
You:     My classifier's stuck at 72% accuracy. Send the
         training config and last epoch's metrics to Desktop.
Code:    [sends config.yaml and metrics via relay]

[System notification appears that a message has been sent to Desktop]

[In Desktop]
You:     /get
Desktop: [fetches config and metrics]
         The loss curve suggests you're underfitting. Learning
         rate 1e-5 is conservative for a model this size...

You:     What would you try?
Desktop: Bump to 3e-5, add warmup steps, and your batch size
         of 8 is small—if memory allows, try 16. Also the
         class imbalance is brutal: 80/15/5 split. Consider
         weighted loss or oversampling the minority classes.

You:     Specify the changes.
Desktop: [sends updated config via relay]

[System notification appears that a message has been sent to Code]

[In Code]
You:     /get
Code:    Got it. Updating config.yaml and adding class weights
         to the loss function.
         [edits files, starts training run]

         Epoch 12: accuracy up to 79%, but precision on
         class 2 dropped. Want Desktop's take?

You:     Yeah, send the confusion matrix.
Code:    [sends via relay]

[In Desktop]
You:     /get
Desktop: Class 2 is getting confused with class 0—they may be
         semantically close. I need more examples.
         [automatically sends request to Code via relay]

📚 Documentation

Usage

• To check for messages from the other side, type get in Desktop or /get in Code. This is the primary way to interact with Relay.

Command variants:

Resource access: You can directly reference messages using @relay:messages://latest. This method is faster than /get and is applicable in plan mode.

Startup preview: When Code starts, you'll see a preview of any pending messages from Desktop. Use /get to read them in full.

Sending messages is straightforward and implicit. When you say "Ask Desktop if this looks right" or "Send the README to Code," the models recognize your intent and trigger the relay automatically.

Notifications

When a message arrives, you'll receive a system notification, eliminating the need for manual polling.

Sound: Add --sound to enable notification sounds. Without a value, it uses platform defaults. With a value, it uses the specified sound:

The duration and display behavior of notifications are controlled by your OS settings.

🔧 Technical Details

• Buffer: The buffer is implemented using SQLite and is located at ~/.relay_buffer.db.
• Rolling window: It stores a maximum of 20 messages. The oldest messages are evicted first.
• Message limit: Each message is limited to 64 KB.
• Idle timeout: The server automatically exits after 1 hour of inactivity.
• Transport: It uses stdio (standard MCP).
• Python: Requires Python 3.9 or higher.

📄 License

No license information provided in the original document.

Tools

Author

Michael Coen — mhcoen@alum.mit.edu · mhcoen@gmail.com