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.
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 menunpx userelay init- reconfigure your editornpx userelay status- check version and toolsnpx userelay --help- see all commands
How does relay compare?
See the full comparison 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.
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_KEYis 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.pngto 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_fetchfile_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_listpdf_extract_textdata_json_formatfile_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_fetchtext_md_to_htmlfile_write
Expected result
A file you can open, review, and share.
Tools
Relay ships with 40 tools across 7 categories.
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
<project>/.cursor/mcp.json
Global config
~/.cursor/mcp.json or %USERPROFILE%\.cursor\mcp.json
{
"mcpServers": {
"relay": {
"command": "relay"
}
}
}
VS Code
Project config
<project>/.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
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/ADDING_A_TOOL.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
Tests
60 tests. 67.0% coverage. all pass.
go test ./... -count=1
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.
Built by Tamish at Valtors. If Relay saves setup time, star the repo.
