# 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`.
[landing](https://valtors.github.io/relay/) - [github](https://github.com/valtors/relay) - [npm](https://www.npmjs.com/package/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)
[](https://github.com/valtors/relay)
---
## Try it
```bash
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
```bash
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.
```bash
npx userelay status
```
```text
relay v0.3.0
tools: 40 registered (7 categories)
transport: stdio (default) | http (with --http)
```
### 2. Detect supported editors
```bash
npx userelay init --list
```
```text
relay init --list
detected editors:
1. Cursor
2. VS Code
```
If your editor is listed, write the config:
```bash
npx userelay init
```
### 3. Verify the local binary
If you installed Relay from source or a release, `relay status` prints the same shape:
```bash
relay status
```
```text
╭─────────────────────────────────╮
│ 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:
```bash
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`
```json
{
"mcpServers": {
"relay": {
"command": "relay"
}
}
}
```
### Cursor
**Project config**
`
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4?s=64)
