{"id":51718662,"url":"https://github.com/valtors/relay","last_synced_at":"2026-07-23T02:01:03.598Z","repository":{"id":369250189,"uuid":"1289051506","full_name":"valtors/relay","owner":"valtors","description":"MCP server with 40 tools for AI agents. Memory, web fetch, search, file ops, screenshots, and multi-agent coordination in one Go binary.","archived":false,"fork":false,"pushed_at":"2026-07-20T12:18:14.000Z","size":311,"stargazers_count":12,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-20T14:10:20.304Z","etag":null,"topics":["agent-memory","agent-orchestration","ai-agents","ai-tools","automation","cli","developer-tools","devtools","go","golang","llm","mcp","mcp-protocol","mcp-server","model-context-protocol","multi-agent","open-source","orchestration","screenshot","web-fetch"],"latest_commit_sha":null,"homepage":"https://valtors.github.io/relay","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/valtors.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["tamish560"]}},"created_at":"2026-07-04T09:28:07.000Z","updated_at":"2026-07-20T12:19:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/valtors/relay","commit_stats":null,"previous_names":["valtors/relay"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/valtors/relay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valtors%2Frelay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valtors%2Frelay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valtors%2Frelay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valtors%2Frelay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valtors","download_url":"https://codeload.github.com/valtors/relay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valtors%2Frelay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35784494,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agent-orchestration","ai-agents","ai-tools","automation","cli","developer-tools","devtools","go","golang","llm","mcp","mcp-protocol","mcp-server","model-context-protocol","multi-agent","open-source","orchestration","screenshot","web-fetch"],"created_at":"2026-07-17T07:00:29.435Z","updated_at":"2026-07-23T02:01:03.538Z","avatar_url":"https://github.com/valtors.png","language":"Go","funding_links":["https://github.com/sponsors/tamish560"],"categories":["Serialization"],"sub_categories":["HTTP Clients"],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/valtors/relay-landing/master/assets/images/relay-logo.png\" alt=\"Relay logo\" width=\"160\" /\u003e\n\n# Relay\n\n**One MCP server for files, images, PDFs, web, and workflows.** Your files stay local. No telemetry. No account. No cloud.\n\nRun it with `npx userelay`.\n\n[![CI](https://img.shields.io/github/actions/workflow/status/valtors/relay/ci.yml?style=for-the-badge\u0026logo=githubactions\u0026label=ci)](https://github.com/valtors/relay/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/userelay?style=for-the-badge\u0026logo=npm\u0026label=npm)](https://www.npmjs.com/package/userelay)\n[![License](https://img.shields.io/github/license/valtors/relay?style=for-the-badge\u0026label=license)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/valtors/relay?style=for-the-badge\u0026logo=github)](https://github.com/valtors/relay/stargazers)\n[![npm downloads](https://img.shields.io/npm/dm/userelay?style=for-the-badge\u0026logo=npm\u0026label=downloads)](https://www.npmjs.com/package/userelay)\n[![contributors](https://img.shields.io/github/contributors/valtors/relay?style=for-the-badge\u0026label=contributors)](https://github.com/valtors/relay/graphs/contributors)\n\n\u003c/div\u003e\n\n---\n\n## Try it\n\n```bash\nnpx userelay\n```\n\nThat opens the setup wizard, downloads the right binary, and configures your editor. No install needed.\n\nIf you already have it:\n\n- `npx userelay` - launch the TUI menu\n- `npx userelay init` - reconfigure your editor\n- `npx userelay status` - check version and tools\n- `npx userelay --help` - see all commands\n\n---\n\n## How does relay compare?\n\nSee the [full comparison](./docs/comparison.md) against standalone MCP servers.\n\n## Why Relay?\n\nEvery 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.\n\nRelay is one binary with 40 tools across 7 categories. One install. One config. One process. When it breaks, you know which thing broke.\n\n| | Relay | Multiple servers |\n|---|---|---|\n| Install | `npx userelay` | One per server |\n| Config | One entry | One per server |\n| Updates | One binary | One per server |\n| Memory | One process | N processes |\n| Tools | 40 built-in | Whatever you assembled |\n\n---\n\n## Install\n\n```bash\nnpx userelay tui\n```\n\nRuns locally. Your files stay on your machine. Type `q` to exit.\n\n---\n\n## What it does\n\n- Runs one MCP server with 40 tools across 7 categories.\n- Reads and writes local files.\n- Resizes, crops, converts, rotates, grayscales, and flips images.\n- Extracts text from PDFs, counts pages, merges files, splits files, and extracts pages.\n- Fetches web pages and checks status codes.\n- Converts CSV, JSON, markdown, base64, and regex output.\n- Works with Claude Desktop, Cursor, VS Code, and other MCP clients.\n- Supports stdio by default and HTTP with `--http`.\n- Enables built-in workflow tools when `ANTHROPIC_API_KEY` is present.\n\nNo pile of single-purpose servers. One binary.\n\n---\n\n## Quickstart\n\n### 1. Check the binary\n\nUse `status` first if you want a one-shot command instead of starting the stdio server.\n\n```bash\nnpx userelay status\n```\n\n```text\nrelay v0.3.0\ntools: 40 registered (7 categories)\ntransport: stdio (default) | http (with --http)\n```\n\n### 2. Detect supported editors\n\n```bash\nnpx userelay init --list\n```\n\n```text\nrelay init --list\n\ndetected editors:\n  1. Cursor\n  2. VS Code\n```\n\nIf your editor is listed, write the config:\n\n```bash\nnpx userelay init\n```\n\n### 3. Verify the local binary\n\nIf you installed Relay from source or a release, `relay status` prints the same shape:\n\n```bash\nrelay status\n```\n\n```text\n  ╭─────────────────────────────────╮\n  │  relay vdev                     │\n  │                                 │\n  │  Tools:      40 (7 categories)  │\n  │  Transport:  stdio | http       │\n  │  Status:     ready              │\n  ╰─────────────────────────────────╯\n```\n\n### 4. Try one result\n\nPrompt your MCP client with this:\n\n\u003e Resize `./screenshots/hero.png` to 1200px wide and save it as `./screenshots/hero-large.png`.\n\nIf that works, Relay is live.\n\n---\n\n## Workflows to try first\n\n### 1. Research a repo or docs page\n\n**Prompt**\n\n\u003e Fetch `https://github.com/pdfcpu/pdfcpu`, summarize what it does, list 3 commands worth trying, and save the notes to `./notes/pdfcpu-summary.md`.\n\n**Relay tools involved**\n\n- `web_fetch`\n- `file_write`\n- text formatting tools as needed\n\n**Expected result**\n\nA local markdown summary your agent can reuse later.\n\n### 2. Turn local PDFs into structured data\n\n**Prompt**\n\n\u003e Read every PDF in `./invoices`, extract the text, pull out all dollar amounts, and save one JSON file at `./invoices/amounts.json`.\n\n**Relay tools involved**\n\n- `file_list`\n- `pdf_extract_text`\n- `data_json_format`\n- `file_write`\n\n**Expected result**\n\nA JSON artifact instead of manual copy-paste from PDFs.\n\n### 3. Fetch the web and ship a usable artifact\n\n**Prompt**\n\n\u003e Fetch `https://example.com/pricing`, turn the important points into markdown, convert that markdown to HTML, and save it as `./research/pricing.html`.\n\n**Relay tools involved**\n\n- `web_fetch`\n- `text_md_to_html`\n- `file_write`\n\n**Expected result**\n\nA file you can open, review, and share.\n\n---\n\n## Tools\n\nRelay ships with 40 tools across 7 categories.\n\n| Category | Tools |\n|---|---|\n| File (7) | read, write, list, size, hash, zip, unzip |\n| Image (7) | info, resize, crop, convert, rotate, grayscale, flip |\n| PDF (6) | info, page count, extract text, extract pages, merge, split |\n| Text (6) | word count, replace, extract regex, base64 encode, base64 decode, md to html |\n| Data (4) | csv to json, json to csv, format json, query json |\n| Web (2) | fetch, status |\n| Workflow (8) | run workflow, PM plan, research, brand, UX, GTM, approval, assemble plan |\n\nList them from the CLI:\n\n```bash\nrelay tools\nrelay tools --json\n```\n\n---\n\n## Client configs\n\nBest option: use `relay init`.\n\nThat 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`.\n\n### Claude Desktop\n\n**macOS**  \n`~/Library/Application Support/Claude/claude_desktop_config.json`\n\n**Windows**  \n`%APPDATA%\\Claude\\claude_desktop_config.json`\n\n**Linux**  \n`~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"relay\": {\n      \"command\": \"relay\"\n    }\n  }\n}\n```\n\n### Cursor\n\n**Project config**  \n`\u003cproject\u003e/.cursor/mcp.json`\n\n**Global config**  \n`~/.cursor/mcp.json` or `%USERPROFILE%\\.cursor\\mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"relay\": {\n      \"command\": \"relay\"\n    }\n  }\n}\n```\n\n### VS Code\n\n**Project config**  \n`\u003cproject\u003e/.vscode/mcp.json`\n\n```json\n{\n  \"servers\": {\n    \"relay\": {\n      \"command\": \"relay\"\n    }\n  }\n}\n```\n\n### Optional workflow tools\n\nMost Relay tools do not need an API key.\n\nIf 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`:\n\n```json\n{\n  \"mcpServers\": {\n    \"relay\": {\n      \"command\": \"relay\",\n      \"env\": {\n        \"ANTHROPIC_API_KEY\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Comparison\n\n| Capability | Relay | Stitching servers together |\n|---|---:|---:|\n| One-command install | ✓ | — |\n| One repo / one binary | ✓ | — |\n| 40 built-in tools | ✓ | — |\n| Minutes to first result | ✓ | — |\n| Local file workflows | ✓ | — |\n| Cross-platform release | ✓ | — |\n| Low ops overhead | ✓ | — |\n\n---\n\n## CLI reference\n\n```text\nrelay              start MCP server in stdio mode\nrelay tui          launch interactive TUI (same as no args in a TTY)\nrelay start        same as above\nrelay start --http serve over Streamable HTTP\nrelay init         detect editor and write config\nrelay init --list  show detected editors\nrelay tools        list all tools\nrelay tools --json list all tools as JSON\nrelay status       version, tool count, transport\nrelay version      print version\nrelay help         usage info\n```\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/valtors/relay\ncd relay\ngo test ./...\ngo run . status\ngo run .\n```\n\nAdd a tool: [docs/ADDING_A_TOOL.md](docs/ADDING_A_TOOL.md)\n\nInstall alternatives:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/valtors/relay/main/scripts/install.sh | sh\n```\n\n```powershell\nirm https://raw.githubusercontent.com/valtors/relay/main/scripts/install.ps1 | iex\n```\n\n```bash\ngo install github.com/valtors/relay@latest\n```\n\n---\n\n## Interactive mode\n\nWhen you run `npx userelay` without arguments in a terminal, Relay launches an interactive TUI:\n\n```text\n  ╭───────────────────────────────────╮\n  │  relay v0.3.0                    │\n  │  40 tools · 7 categories         │\n  ╰───────────────────────────────────╯\n\n  ❯ Start MCP server (stdio)\n    Start MCP server (HTTP)\n    Initialize — detect \u0026 configure editors\n    Browse tools\n    Status\n    Quit\n```\n\n- Animated RELAY wordmark on launch (shimmer effect)\n- Keyboard-navigable menus\n- Init wizard with editor detection and config writing\n- Tools browser — all 40 tools organized by category\n- Status dashboard — version, transport, tool count\n\nIf stdin is not a TTY (piped, CI, or MCP client), Relay starts the server directly — no TUI.\n\nTo explicitly launch the TUI: `npx userelay tui`\n\n---\n\n## Roadmap\n\n**Shipped:**\n- 40 built-in tools across 7 categories\n- Cross-platform install (npm, curl, go install)\n- MCP server over stdio and HTTP\n- Editor config helper (`relay init`)\n- Interactive TUI mode\n- Security hardening (path traversal, SSRF, XSS, prompt injection)\n- GoReleaser CI/CD\n\n**Next:**\n- Tool plugin system (define tools in external files)\n- Streaming responses for long-running operations\n- More verified starter workflows\n- Community-contributed tools\n- MCP server discovery and registry\n\n**Thinking about:**\n- Docker image for containerized deployments\n- WebSocket transport\n- Tool-level permissions and sandboxing\n- Multi-language tool definitions (Python, JS plugins)\n\n---\n\n## Contributors\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/leemeo3\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/117142323?v=4?s=64\" width=\"64px;\" alt=\"Lee Sang Hoon\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eLee Sang Hoon\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/valtors/relay/commits?author=leemeo3\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/valtors/relay/commits?author=leemeo3\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/rubysnewjourney\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/283093796?v=4?s=64\" width=\"64px;\" alt=\"rubysnewjourney\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003erubysnewjourney\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/valtors/relay/commits?author=rubysnewjourney\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/valtors/relay/commits?author=rubysnewjourney\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n  \u003ctfoot\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" size=\"13px\" colspan=\"7\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/all-contributors/all-contributors-cli/1b8533af435da9854653492b1327a23a4dbd0a10/assets/logo-small.svg\"\u003e\n          \u003ca href=\"https://all-contributors.js.org/docs/en/bot/usage\"\u003eAdd your contributions\u003c/a\u003e\n        \u003c/img\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tfoot\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nWant to be here? Check [`good first issues`](https://github.com/valtors/relay/labels/good%20first%20issue).\n\n---\n\n## Companion Project\n\n[**Reflow**](https://github.com/valtors/reflow) - an SSR-safe responsive toolkit for TypeScript. Breakpoints, container queries, fluid typography, and user preference hooks across 8 frameworks. Same org, same philosophy.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\nBuilt by [Tamish](https://github.com/tamish560) at [Valtors](https://github.com/valtors). If Relay saves setup time, star the repo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaltors%2Frelay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaltors%2Frelay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaltors%2Frelay/lists"}