Relay MCP server
Commit Nov 7, 2026Provides an all-in-one MCP server with 40 tools for file operations, image processing, PDF manipulation, web fetching, and automated workflows.
Also known as valtors/relay
- Stars
- 12
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 7, 2026
- License
- MIT
What is Relay MCP?
Relay provides an all-in-one MCP server with 40 tools for file operations, image processing, PDF manipulation, web fetching, and automated workflows.
Summary generated from the project's README
About Relay MCP server
Managing local files, images, and web data through a single interface is what Relay enables for developers using MCP clients like Claude Desktop, Cursor, or VS Code. Instead of installing multiple separate servers for different tasks, this single binary provides 40 tools organized into seven categories including file operations, image processing, PDF manipulation, and web fetching. It runs locally on your machine, ensuring your files stay private without requiring any accounts or cloud services.
Users can set up the environment quickly using the npx userelay command, which includes a setup wizard to configure editors automatically. The server supports stdio by default but can also run over HTTP using the --http flag. While most tools function without external credentials, providing an ANTHROPIC_API_KEY enables specialized workflow tools such as pm_plan, run_research, and run_ux to assist with complex planning and research tasks.
What you can do with it
- 1Automated Research and DocumentationAn AI agent can fetch documentation from a website, summarize the content, and save the resulting notes as a local markdown file.
- 2Structured Data Extraction from PDFsYou can instruct a client to scan a directory of PDF invoices to extract specific text and compile all dollar amounts into a single JSON file.
- 3Image Transformation WorkflowsA developer can ask an AI to perform specific edits on an image file, such as resizing it to a specific width and saving the new version.
- 4Web Content ConversionThe server can fetch a webpage, convert the key information into markdown, and then transform that markdown into an HTML file.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ANTHROPIC_API_KEY
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablevaltors/relay is public and reachablegithub.com/valtors/relay ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/valtors/relay ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubRelay
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.
| 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_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.
| 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
<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
| 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/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.
Relay MCP questions
Does Relay require an account or cloud connection?
No, Relay runs locally with no telemetry, no account, and no cloud required.
What kind of tools are included in Relay?
Relay includes 40 tools across 7 categories: File, Image, PDF, Text, Data, Web, and Workflow.
Can I use Relay with Claude Desktop or Cursor?
Yes, it is compatible with Claude Desktop, Cursor, VS Code, and other MCP clients.