Relay

Relay

One MCP server for files, images, PDFs, web, and workflows. Your files stay local. No telemetry. No account. No cloud.

Run it with npx userelay.

[](https://github.com/valtors/relay/actions/workflows/ci.yml) [](https://www.npmjs.com/package/userelay) [](LICENSE) [](https://github.com/valtors/relay/stargazers) [](https://www.npmjs.com/package/userelay) [](https://github.com/valtors/relay/graphs/contributors)

---

Try it

npx userelay

That opens the setup wizard, downloads the right binary, and configures your editor. No install needed.

If you already have it:

• npx userelay - launch the TUI menu
• npx userelay init - reconfigure your editor
• npx userelay status - check version and tools
• npx userelay --help - see all commands

---

How does relay compare?

See the [full comparison](./docs/comparison.md) against standalone MCP servers.

Why Relay?

Every MCP server does one thing. File server. Image server. PDF server. Web fetch server. You stitch 5 of them together and each one has its own install, its own config, its own update cycle, its own way of breaking.

Relay is one binary with 40 tools across 7 categories. One install. One config. One process. When it breaks, you know which thing broke.

| | Relay | Multiple servers | |---|---|---| | Install | npx userelay | One per server | | Config | One entry | One per server | | Updates | One binary | One per server | | Memory | One process | N processes | | Tools | 40 built-in | Whatever you assembled |

---

Install

npx userelay tui

Runs locally. Your files stay on your machine. Type q to exit.

---

What it does

• Runs one MCP server with 40 tools across 7 categories.
• Reads and writes local files.
• Resizes, crops, converts, rotates, grayscales, and flips images.
• Extracts text from PDFs, counts pages, merges files, splits files, and extracts pages.
• Fetches web pages and checks status codes.
• Converts CSV, JSON, markdown, base64, and regex output.
• Works with Claude Desktop, Cursor, VS Code, and other MCP clients.
• Supports stdio by default and HTTP with --http.
• Enables built-in workflow tools when ANTHROPIC_API_KEY is present.

No pile of single-purpose servers. One binary.

---

Quickstart

1. Check the binary

Use status first if you want a one-shot command instead of starting the stdio server.

npx userelay status

relay v0.3.0
tools: 40 registered (7 categories)
transport: stdio (default) | http (with --http)

2. Detect supported editors

npx userelay init --list

relay init --list

detected editors:
  1. Cursor
  2. VS Code

If your editor is listed, write the config:

npx userelay init

3. Verify the local binary

If you installed Relay from source or a release, relay status prints the same shape:

relay status

  ╭─────────────────────────────────╮
  │  relay vdev                     │
  │                                 │
  │  Tools:      40 (7 categories)  │
  │  Transport:  stdio | http       │
  │  Status:     ready              │
  ╰─────────────────────────────────╯

4. Try one result

Prompt your MCP client with this:

> Resize ./screenshots/hero.png to 1200px wide and save it as ./screenshots/hero-large.png.

If that works, Relay is live.

---

Workflows to try first

1. Research a repo or docs page

Prompt

> Fetch https://github.com/pdfcpu/pdfcpu, summarize what it does, list 3 commands worth trying, and save the notes to ./notes/pdfcpu-summary.md.

Relay tools involved

• web_fetch
• file_write
• text formatting tools as needed

Expected result

A local markdown summary your agent can reuse later.

2. Turn local PDFs into structured data

Prompt

> Read every PDF in ./invoices, extract the text, pull out all dollar amounts, and save one JSON file at ./invoices/amounts.json.

Relay tools involved

• file_list
• pdf_extract_text
• data_json_format
• file_write

Expected result

A JSON artifact instead of manual copy-paste from PDFs.

3. Fetch the web and ship a usable artifact

Prompt

> Fetch https://example.com/pricing, turn the important points into markdown, convert that markdown to HTML, and save it as ./research/pricing.html.

Relay tools involved

• web_fetch
• text_md_to_html
• file_write

Expected result

A file you can open, review, and share.

---

Tools

Relay ships with 40 tools across 7 categories.

| Category | Tools | |---|---| | File (7) | read, write, list, size, hash, zip, unzip | | Image (7) | info, resize, crop, convert, rotate, grayscale, flip | | PDF (6) | info, page count, extract text, extract pages, merge, split | | Text (6) | word count, replace, extract regex, base64 encode, base64 decode, md to html | | Data (4) | csv to json, json to csv, format json, query json | | Web (2) | fetch, status | | Workflow (8) | run workflow, PM plan, research, brand, UX, GTM, approval, assemble plan |

List them from the CLI:

relay tools
relay tools --json

---

Client configs

Best option: use relay init.

That writes the right JSON shape for the detected editor and uses the installed binary path. If you want to paste config manually, use the snippets below. They assume relay is already on your PATH. If your client cannot find it, replace "relay" with the full path from which relay or where relay.

Claude Desktop

macOS ~/Library/Application Support/Claude/claude_desktop_config.json

Windows %APPDATA%\Claude\claude_desktop_config.json

Linux ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "relay": {
      "command": "relay"
    }
  }
}

Cursor

Project config /.cursor/mcp.json

Global config ~/.cursor/mcp.json or %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "relay": {
      "command": "relay"
    }
  }
}

VS Code

Project config /.vscode/mcp.json

{
  "servers": {
    "relay": {
      "command": "relay"
    }
  }
}

Optional workflow tools

Most Relay tools do not need an API key.

If you want the built-in planning and workflow tools (run_workflow, pm_plan, run_research, run_brand, run_ux, run_gtm, assemble_plan), add ANTHROPIC_API_KEY under env:

{
  "mcpServers": {
    "relay": {
      "command": "relay",
      "env": {
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

---

Comparison

| Capability | Relay | Stitching servers together | |---|---:|---:| | One-command install | ✓ | — | | One repo / one binary | ✓ | — | | 40 built-in tools | ✓ | — | | Minutes to first result | ✓ | — | | Local file workflows | ✓ | — | | Cross-platform release | ✓ | — | | Low ops overhead | ✓ | — |

---

CLI reference

relay              start MCP server in stdio mode
relay tui          launch interactive TUI (same as no args in a TTY)
relay start        same as above
relay start --http serve over Streamable HTTP
relay init         detect editor and write config
relay init --list  show detected editors
relay tools        list all tools
relay tools --json list all tools as JSON
relay status       version, tool count, transport
relay version      print version
relay help         usage info

---

Development

git clone https://github.com/valtors/relay
cd relay
go test ./...
go run . status
go run .

Add a tool: [docs/ADDINGATOOL.md](docs/ADDINGATOOL.md)

Install alternatives:

curl -fsSL https://raw.githubusercontent.com/valtors/relay/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/valtors/relay/main/scripts/install.ps1 | iex

go install github.com/valtors/relay@latest

---

Interactive mode

When you run npx userelay without arguments in a terminal, Relay launches an interactive TUI:

  ╭───────────────────────────────────╮
  │  relay v0.3.0                    │
  │  40 tools · 7 categories         │
  ╰───────────────────────────────────╯

  ❯ Start MCP server (stdio)
    Start MCP server (HTTP)
    Initialize — detect & configure editors
    Browse tools
    Status
    Quit

• Animated RELAY wordmark on launch (shimmer effect)
• Keyboard-navigable menus
• Init wizard with editor detection and config writing
• Tools browser — all 40 tools organized by category
• Status dashboard — version, transport, tool count

If stdin is not a TTY (piped, CI, or MCP client), Relay starts the server directly — no TUI.

To explicitly launch the TUI: npx userelay tui

---

Roadmap

Shipped:

• 40 built-in tools across 7 categories
• Cross-platform install (npm, curl, go install)
• MCP server over stdio and HTTP
• Editor config helper (relay init)
• Interactive TUI mode
• Security hardening (path traversal, SSRF, XSS, prompt injection)
• GoReleaser CI/CD

Next:

• Tool plugin system (define tools in external files)
• Streaming responses for long-running operations
• More verified starter workflows
• Community-contributed tools
• MCP server discovery and registry

Thinking about:

• Docker image for containerized deployments
• WebSocket transport
• Tool-level permissions and sandboxing
• Multi-language tool definitions (Python, JS plugins)

---

Contributors

Lee Sang Hoon💻 📖

Add your contributions

Want to be here? Check good first issues.

---

Companion Project

Reflow - an SSR-safe responsive toolkit for TypeScript. Breakpoints, container queries, fluid typography, and user preference hooks across 8 frameworks. Same org, same philosophy.

License

MIT. See [LICENSE](LICENSE).

Built by Tamish at Valtors. If Relay saves setup time, star the repo.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: valtors
• Source: valtors/relay
• License: MIT
• Homepage: https://valtors.github.io/relay

Install and usage instructions live in the source repository linked above.