mcp-remote CLI
An adapter that connects an MCP client limited to local stdio servers to a remote MCP server over HTTP or SSE, with authorization
- 1,668 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Forwards traffic and credentials to whatever remote server you configure
- Stores and refreshes OAuth tokens locally
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/mcp-remoteDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Forwards traffic and credentials to whatever remote server you configure
- Stores and refreshes OAuth tokens locally
This is third-party code. Review the repository files before installing.
What it does
mcp-remote is a bridge between an MCP client that only speaks local stdio and a remote MCP server over HTTP or SSE. It runs through npx inside the mcpServers config and handles the OAuth flow, token refresh and local token storage for you. It supports custom headers and a header file, per-resource session isolation via RFC 8707, extra authorization parameters, callback port and host selection, timeouts, keep-alive, proxy support and filtering of the remote server's tools. It fills the gap until popular clients reach remote authorized servers on their own.
Who it is for. For users of Claude Desktop, Cursor, Windsurf and other clients who need to reach a remote MCP server that requires authorization.
Good fit when
- Your client only supports local stdio servers but you need a remote one
- The remote server needs OAuth or custom headers
- You need to keep several accounts of one server in separate sessions
Not a fit when
- Your client already connects to remote authorized servers directly
- You need an actual MCP server rather than an adapter to one
Example request
Connect me to this remote MCP server over its URL using mcp-remoteLimitations
It is an adapter, not a server: it only forwards traffic to a remote server and passes it your credentials and headers. OAuth tokens are stored locally in the ~/.mcp-auth directory. Some clients mishandle spaces in args, and the README gives workarounds via environment variables or a header file. Reaching a given remote server depends on that server.
How to disable. Remove the server entry from the mcpServers block in your client config. The auth cache lives in the ~/.mcp-auth directory.
FAQ
Is this a standalone MCP server?
No. It is an adapter that connects an stdio client to a remote server over HTTP or SSE and runs the authorization for it.
Where do the tokens go?
OAuth tokens and session data are stored locally in the ~/.mcp-auth directory, separately for each combination of URL, resource and headers.
Discussion
No questions or reviews yet.
Related
CLI toolsA universal MCP CLI client from Apify: persistent sessions, OAuth, JSON output for scripts and shell access to any MCP server for agents
An Open WebUI proxy that exposes any MCP server as an HTTP API with an OpenAPI schema
An MCP server that installs other MCP servers from npm and PyPI at the agent's request and writes them into the config
A CLI for any MCP server: list and call tools, resources and prompts, run mock and proxy modes, guard access and manage agent configs
The mcpl CLI searches tools across several MCP servers and calls them from the terminal, with OAuth sign-in done by a human
A CLI that turns any MCP server, OpenAPI spec or GraphQL endpoint into commands at runtime, with no codegen
README in short
The README explains why the adapter exists: most clients only work with local stdio servers and cannot yet run OAuth against remote ones. mcp-remote runs through npx and closes that gap. The docs cover the flags in detail: custom headers and a header file, the --resource flag for session isolation, extra authorization parameters, callback port and host, timeouts, keep-alive, proxy support and tool filtering. It also documents workarounds for clients that mangle spaces in args.