{"id":47298388,"url":"https://github.com/avelino/mcp","last_synced_at":"2026-04-13T03:26:27.485Z","repository":{"id":344706178,"uuid":"1182696056","full_name":"avelino/mcp","owner":"avelino","description":"CLI that turns MCP servers into terminal commands, single binary","archived":false,"fork":false,"pushed_at":"2026-03-29T20:34:47.000Z","size":223,"stargazers_count":33,"open_issues_count":10,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T22:09:44.281Z","etag":null,"topics":["cli","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"https://mcp.avelino.run","language":"Rust","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/avelino.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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}},"created_at":"2026-03-15T21:15:30.000Z","updated_at":"2026-03-29T20:32:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/avelino/mcp","commit_stats":null,"previous_names":["avelino/mcp"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/avelino/mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avelino%2Fmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avelino%2Fmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avelino%2Fmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avelino%2Fmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avelino","download_url":"https://codeload.github.com/avelino/mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avelino%2Fmcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290537,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cli","mcp","mcp-server"],"created_at":"2026-03-16T20:05:11.372Z","updated_at":"2026-04-13T03:26:27.467Z","avatar_url":"https://github.com/avelino.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# mcp\n\nCLI that turns [MCP servers](https://modelcontextprotocol.io/) into terminal commands.\n\n```\nmcp sentry search_issues '{\"query\": \"is:unresolved level:error\"}'\n```\n\nNo SDKs. No wrapper code. One binary, any MCP server.\n\n## What it does\n\nMCP (Model Context Protocol) servers expose tools — search issues, query logs, send messages, read files. This CLI lets you call those tools directly from your terminal. You configure a server once, then use it like any other command.\n\n```\n$ mcp slack list_channels\n$ mcp grafana search_dashboards '{\"query\": \"api-latency\"}'\n$ mcp sentry get_issue_details '{\"issue_id\": \"12345\"}'\n```\n\nOutput is always JSON. Pipe it, `jq` it, script it.\n\n## Quick start\n\n**Install:**\n\n```bash\n# Homebrew (macOS and Linux)\nbrew install avelino/mcp/mcp\n\n# Docker\ndocker pull ghcr.io/avelino/mcp\nalias mcp='docker run --rm -v ~/.config/mcp:/root/.config/mcp ghcr.io/avelino/mcp'\n\n# Pre-built binary from GitHub Releases\n# Download the latest from https://github.com/avelino/mcp/releases\n\n# From source (requires Rust)\ncargo install --path .\n```\n\n**Add a server from the registry:**\n\n```bash\nmcp add filesystem\n```\n\n**Or add an HTTP server manually:**\n\n```bash\nmcp add --url https://mcp.sentry.dev/sse sentry\n```\n\n**See what tools are available:**\n\n```bash\nmcp sentry --list\n```\n\n**Call a tool:**\n\n```bash\nmcp sentry search_issues '{\"query\": \"is:unresolved\"}'\n```\n\nThat's it. You're using MCP.\n\n## How it works\n\n```\nYou  --\u003e  mcp CLI  --\u003e  MCP Server  --\u003e  Service API\n              |\n         servers.json\n```\n\nThe CLI reads your config (`~/.config/mcp/servers.json`), connects to the server using stdio or HTTP, and speaks [JSON-RPC 2.0](https://www.jsonrpc.org/specification) to call tools. Authentication (OAuth 2.0, API tokens) is handled automatically.\n\n## Configuration\n\nServers live in `~/.config/mcp/servers.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"slack\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"slack-mcp-server@latest\", \"--transport\", \"stdio\"],\n      \"env\": {\n        \"SLACK_MCP_XOXP_TOKEN\": \"${SLACK_TOKEN}\",\n        \"SLACK_MCP_TEAM_ID\": \"${SLACK_TEAM_ID}\"\n      }\n    },\n    \"sentry\": {\n      \"url\": \"https://mcp.sentry.dev/sse\"\n    }\n  }\n}\n```\n\nThree types of servers:\n- **Stdio** — the CLI spawns a local process (`command` + `args`)\n- **HTTP** — the CLI connects to a remote URL (`url` + optional `headers`)\n- **CLI** — wraps any command-line tool as an MCP server (`command` + `cli: true`)\n\nEnvironment variables use `${VAR_NAME}` syntax and are resolved at runtime.\n\n## Authentication\n\nFor HTTP servers that require auth, `mcp` handles it automatically:\n\n1. **OAuth 2.0** — If the server supports it, `mcp` opens your browser, completes the flow, and saves the token\n2. **Manual token** — If OAuth isn't available, it guides you to get a token with service-specific instructions\n3. **Config headers** — You can set `Authorization` headers directly in config\n\nTokens are saved in `~/.config/mcp/auth.json` and refreshed automatically.\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `mcp --list` | List configured servers |\n| `mcp \u003cserver\u003e --list` | List available tools |\n| `mcp \u003cserver\u003e --info` | List tools with input schemas |\n| `mcp \u003cserver\u003e \u003ctool\u003e [json]` | Call a tool |\n| `mcp search \u003cquery\u003e` | Search the MCP server registry |\n| `mcp add \u003cname\u003e` | Add a server from registry |\n| `mcp add --url \u003curl\u003e \u003cname\u003e` | Add an HTTP server |\n| `mcp remove \u003cname\u003e` | Remove a server |\n| `mcp update \u003cname\u003e` | Refresh a server's config from the registry (preserves your customizations) |\n| `mcp serve` | Start proxy — all servers as one MCP endpoint |\n| `mcp logs` | Show audit log entries |\n| `mcp logs --errors` | Show only failures |\n| `mcp logs -f` | Follow mode — stream new entries live |\n\n## Piping JSON from stdin\n\nIf you don't pass JSON arguments on the command line, `mcp` reads from stdin:\n\n```bash\necho '{\"query\": \"is:unresolved\"}' | mcp sentry search_issues\n```\n\n## Docker\n\nThe CLI is available as a multi-arch Docker image (amd64/arm64):\n\n```bash\n# Run directly\ndocker run --rm -v ~/.config/mcp:/root/.config/mcp ghcr.io/avelino/mcp --list\n\n# Call a tool\ndocker run --rm -v ~/.config/mcp:/root/.config/mcp ghcr.io/avelino/mcp sentry search_issues '{\"query\": \"is:unresolved\"}'\n\n# Pass environment variables for servers that need them\ndocker run --rm \\\n  -v ~/.config/mcp:/root/.config/mcp \\\n  -e GITHUB_TOKEN \\\n  ghcr.io/avelino/mcp github search_repositories '{\"query\": \"mcp\"}'\n\n# Use an alias for convenience\nalias mcp='docker run --rm -v ~/.config/mcp:/root/.config/mcp ghcr.io/avelino/mcp'\nmcp sentry --list\n```\n\nAvailable tags:\n\n| Tag | Description |\n|---|---|\n| `latest` | Latest stable release |\n| `x.y.z` | Pinned version |\n| `beta` | Latest build from main branch |\n\n## CLI as MCP\n\nAny command-line tool becomes an MCP server — no code, no wrapper:\n\n```json\n{\n  \"mcpServers\": {\n    \"kubectl\": {\n      \"command\": \"kubectl\",\n      \"cli\": true,\n      \"cli_only\": [\"get\", \"describe\", \"logs\", \"version\"]\n    }\n  }\n}\n```\n\n`mcp` parses `--help` automatically to discover subcommands and flags, then exposes them as MCP tools:\n\n```bash\n$ mcp kubectl --list\nkubectl_get        Display one or many resources\nkubectl_describe   Show details of a specific resource\nkubectl_version    Print the client and server version information\n\n$ mcp kubectl kubectl_get '{\"args\": \"pods -A\", \"output\": \"json\"}'\n```\n\nWorks with kubectl, docker, terraform, git — anything with `--help`. See the [CLI as MCP guide](docs/guides/cli-as-mcp.md) for details.\n\n## Proxy mode\n\nUse `mcp serve` to expose all your configured servers as a single MCP endpoint. Configure it once, use it from any LLM tool:\n\n```json\n{\n  \"mcpServers\": {\n    \"all\": {\n      \"command\": \"mcp\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\nThis works with Claude Code, Cursor, Windsurf, or any MCP-compatible client. Tools are namespaced as `server__tool` (e.g. `sentry__search_issues`). See the [proxy mode guide](docs/guides/proxy-mode.md) for details.\n\n### Smart resource management\n\nEvery MCP client (Claude Code, Cursor, Windsurf) spawns all backend servers at startup and keeps them alive forever. With 10 servers and 3 sessions open, that's 30 idle processes eating ~3 GB of RAM.\n\nThe `mcp` proxy fixes this with **persistent tool cache**, **lazy initialization**, **shared backends across clients**, and **adaptive idle shutdown**:\n\n- **Instant startup** — tools are cached to disk and served immediately, even before backends connect\n- **One backend = one process, no matter how many clients** — 5 editor sessions hitting `slack` share a single `slack-mcp-server` child. Calls run in parallel via JSON-RPC id multiplexing on stdio.\n- Backends only connect when you actually use them (background refresh keeps the cache fresh)\n- Idle backends are shut down automatically (1-5 min based on usage frequency), with a warm-up grace period so a brand-new backend isn't reaped before its first use\n- Tools stay visible — reconnection is transparent on next call\n- Cache invalidates automatically when backend config changes\n- Zero orphans: every spawned child is reaped on shutdown, panic, cancel, or stalled close (`kill_on_drop` everywhere)\n\n```json\n{\n  \"mcpServers\": {\n    \"slack\": {\n      \"command\": \"npx\",\n      \"args\": [\"@anthropic/mcp-slack\"],\n      \"idle_timeout\": \"adaptive\"\n    },\n    \"sentry\": {\n      \"url\": \"https://mcp.sentry.io\",\n      \"idle_timeout\": \"never\"\n    }\n  }\n}\n```\n\nRead the full story: **[MCP servers are draining your hardware](https://mcp.avelino.run/mcp-servers-are-draining-your-hardware)**\n\n## Audit logging\n\nEvery operation is logged — tool calls, searches, config changes, proxy requests. Query the log with filters or stream it in real-time:\n\n```bash\nmcp logs                          # recent entries\nmcp logs --server sentry --errors # sentry failures only\nmcp logs --since 1h               # last hour\nmcp logs -f                       # follow mode (tail -f)\nmcp logs --json | jq '...'        # pipe to jq\n```\n\nLogs are stored locally in an embedded database. No external services, no network calls. See the [audit logging guide](docs/guides/audit-logging.md) for configuration and details.\n\n## Environment variables\n\n| Variable | Description |\n|---|---|\n| `MCP_CONFIG_PATH` | Override config file location |\n| `MCP_TIMEOUT` | Timeout in seconds for stdio servers (default: 60) |\n\n## Documentation\n\nFull documentation: [docs/](docs/README.md)\n\n## Development\n\n```bash\ncargo build\ncargo test\n```\n\n## Contributing\n\n1. Fork the repo\n2. Create your branch (`git checkout -b my-feature`)\n3. Make your changes\n4. Run tests (`cargo test`)\n5. Submit a pull request\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favelino%2Fmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favelino%2Fmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favelino%2Fmcp/lists"}