fastmcp-remote 3.4.0__tar.gz

fastmcp_remote-3.4.0/.gitignore

@@ -0,0 +1,80 @@
+# Python-generated files
+__pycache__/
+*.py[cod]
+*$py.class
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+.pytest_cache/
+.loq_cache
+.coverage
+htmlcov/
+.tox/
+nosetests.xml
+coverage.xml
+*.cover
+
+# Virtual environments
+.venv
+venv/
+env/
+ENV/
+.env
+
+# System files
+.DS_Store
+
+# Version file
+src/fastmcp/_version.py
+
+# Editors and IDEs
+.cursorrules
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# Local development
+.python-version
+.envrc
+.envrc.private
+.direnv/
+
+# Logs and databases
+*.log
+*.sqlite
+*.db
+*.ddb
+
+# Claude worktree management
+.claude-wt/worktrees
+.claude/worktrees/
+
+# Agents
+/PLAN.md
+/TODO.md
+/STATUS.md
+plans/
+
+# Common FastMCP test files
+/test.py
+/server.py
+/client.py
+/test.json

fastmcp_remote-3.4.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: fastmcp-remote
+Version: 3.4.0
+Summary: A Python stdio bridge for remote MCP servers, powered by FastMCP.
+Project-URL: Homepage, https://gofastmcp.com
+Project-URL: Repository, https://github.com/PrefectHQ/fastmcp
+Project-URL: Documentation, https://gofastmcp.com
+Project-URL: Original npm project, https://github.com/geelen/mcp-remote
+Author: Jeremiah Lowin
+License-Expression: Apache-2.0
+Keywords: fastmcp,fastmcp remote,mcp,mcp remote,model context protocol,oauth,stdio
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastmcp-slim[client,server]==3.4.0
+Description-Content-Type: text/markdown
+
+# fastmcp-remote
+
+`fastmcp-remote` is FastMCP's standalone Python stdio bridge for remote MCP servers. It lets MCP clients that launch local stdio processes connect to MCP servers hosted over Streamable HTTP or SSE.
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "uvx",
+      "args": ["fastmcp-remote", "https://mcp.linear.app/mcp"]
+    }
+  }
+}
+```
+
+The CLI is powered by [FastMCP](https://gofastmcp.com). Its command shape is inspired by the original [`mcp-remote`](https://github.com/geelen/mcp-remote) npm project, which established the stdio-to-remote bridge pattern used across the MCP ecosystem.
+
+`fastmcp-remote` is intentionally smaller than the general FastMCP CLI. It does not load Python files, discover local MCP configs, prepare project environments, or run development reload loops. It builds one FastMCP client for the URL you provide, exposes that client as a local stdio proxy, and leaves the rest alone.
+
+## Usage
+
+Run a remote MCP server through a local stdio bridge:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp
+```
+
+Use the full MCP endpoint URL for the remote server. Many FastMCP HTTP servers expose MCP at `/mcp`, so a local development server may need `http://localhost:8000/mcp` rather than `http://localhost:8000`.
+
+`fastmcp-remote` starts a local stdio bridge, then connects to the upstream server when the MCP host initializes that bridge. If the upstream server is unavailable, the URL does not point to an MCP endpoint, or authentication cannot complete, initialization fails and the host should report the remote server as failed.
+
+For authenticated MCP servers, OAuth is enabled automatically. To pass a bearer token or other custom header instead, provide a header. The header name ends at the first colon, so values can contain additional colons. Quote the header when the value contains spaces, just like any other shell argument:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp \
+  --header "Authorization: Bearer <token>"
+```
+
+Repeat `--header` to send multiple headers. Header values use `Name: Value` format:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp \
+  --header "Authorization: Bearer <token>" \
+  --header "X-Workspace: production" \
+  --header "X-Client-Name: My MCP Host" \
+  --header "X-Callback-Url: https://example.com/oauth/callback"
+```
+
+Some MCP hosts on Windows have trouble preserving spaces inside command arguments. Put the spaced value in an environment variable and reference it from the header value:
+
+```json
+{
+  "mcpServers": {
+    "remote-api": {
+      "command": "uvx",
+      "args": [
+        "fastmcp-remote",
+        "https://example.com/mcp",
+        "--header",
+        "Authorization:${AUTH_HEADER}"
+      ],
+      "env": {
+        "AUTH_HEADER": "Bearer <token>"
+      }
+    }
+  }
+}
+```
+
+Use `--auth none` for unauthenticated development servers:
+
+```bash
+uvx fastmcp-remote http://localhost:8000/mcp --auth none
+```
+
+## Options
+
+- `--transport`: Choose `http` or `sse`. Defaults to `http`.
+- `--header`: Add a header to upstream requests, for example `--header "Authorization: Bearer <token>"`. Values may contain colons. Quote headers whose values contain spaces. Use `${VAR}` to expand environment variables inside values. Repeat for multiple headers.
+- `--resource`: Isolate OAuth token storage for a named remote resource.
+- `--host`: Set the OAuth callback hostname. Defaults to `localhost`.
+- `--auth-timeout`: Set how long to wait for the OAuth callback. Defaults to 300 seconds.
+- `--ignore-tool`: Hide tools whose names match a glob pattern.
+- `--auth`: Choose `oauth` or `none`. The default uses OAuth unless an `Authorization` header is provided.
+
+OAuth tokens are stored under `~/.fastmcp/remote` by default. Set `FASTMCP_REMOTE_CONFIG_DIR` to use another directory.

fastmcp_remote-3.4.0/README.md

@@ -0,0 +1,86 @@
+# fastmcp-remote
+
+`fastmcp-remote` is FastMCP's standalone Python stdio bridge for remote MCP servers. It lets MCP clients that launch local stdio processes connect to MCP servers hosted over Streamable HTTP or SSE.
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "uvx",
+      "args": ["fastmcp-remote", "https://mcp.linear.app/mcp"]
+    }
+  }
+}
+```
+
+The CLI is powered by [FastMCP](https://gofastmcp.com). Its command shape is inspired by the original [`mcp-remote`](https://github.com/geelen/mcp-remote) npm project, which established the stdio-to-remote bridge pattern used across the MCP ecosystem.
+
+`fastmcp-remote` is intentionally smaller than the general FastMCP CLI. It does not load Python files, discover local MCP configs, prepare project environments, or run development reload loops. It builds one FastMCP client for the URL you provide, exposes that client as a local stdio proxy, and leaves the rest alone.
+
+## Usage
+
+Run a remote MCP server through a local stdio bridge:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp
+```
+
+Use the full MCP endpoint URL for the remote server. Many FastMCP HTTP servers expose MCP at `/mcp`, so a local development server may need `http://localhost:8000/mcp` rather than `http://localhost:8000`.
+
+`fastmcp-remote` starts a local stdio bridge, then connects to the upstream server when the MCP host initializes that bridge. If the upstream server is unavailable, the URL does not point to an MCP endpoint, or authentication cannot complete, initialization fails and the host should report the remote server as failed.
+
+For authenticated MCP servers, OAuth is enabled automatically. To pass a bearer token or other custom header instead, provide a header. The header name ends at the first colon, so values can contain additional colons. Quote the header when the value contains spaces, just like any other shell argument:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp \
+  --header "Authorization: Bearer <token>"
+```
+
+Repeat `--header` to send multiple headers. Header values use `Name: Value` format:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp \
+  --header "Authorization: Bearer <token>" \
+  --header "X-Workspace: production" \
+  --header "X-Client-Name: My MCP Host" \
+  --header "X-Callback-Url: https://example.com/oauth/callback"
+```
+
+Some MCP hosts on Windows have trouble preserving spaces inside command arguments. Put the spaced value in an environment variable and reference it from the header value:
+
+```json
+{
+  "mcpServers": {
+    "remote-api": {
+      "command": "uvx",
+      "args": [
+        "fastmcp-remote",
+        "https://example.com/mcp",
+        "--header",
+        "Authorization:${AUTH_HEADER}"
+      ],
+      "env": {
+        "AUTH_HEADER": "Bearer <token>"
+      }
+    }
+  }
+}
+```
+
+Use `--auth none` for unauthenticated development servers:
+
+```bash
+uvx fastmcp-remote http://localhost:8000/mcp --auth none
+```
+
+## Options
+
+- `--transport`: Choose `http` or `sse`. Defaults to `http`.
+- `--header`: Add a header to upstream requests, for example `--header "Authorization: Bearer <token>"`. Values may contain colons. Quote headers whose values contain spaces. Use `${VAR}` to expand environment variables inside values. Repeat for multiple headers.
+- `--resource`: Isolate OAuth token storage for a named remote resource.
+- `--host`: Set the OAuth callback hostname. Defaults to `localhost`.
+- `--auth-timeout`: Set how long to wait for the OAuth callback. Defaults to 300 seconds.
+- `--ignore-tool`: Hide tools whose names match a glob pattern.
+- `--auth`: Choose `oauth` or `none`. The default uses OAuth unless an `Authorization` header is provided.
+
+OAuth tokens are stored under `~/.fastmcp/remote` by default. Set `FASTMCP_REMOTE_CONFIG_DIR` to use another directory.

fastmcp_remote-3.4.0/fastmcp_remote/__init__.py

@@ -0,0 +1,10 @@
+"""Python stdio bridge for remote MCP servers."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("fastmcp-remote")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

fastmcp_remote-3.4.0/fastmcp_remote/cli.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import hashlib
+import os
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+from urllib.parse import urlparse
+
+import anyio
+from key_value.aio.protocols import AsyncKeyValue
+from key_value.aio.stores.filetree import (
+    FileTreeStore,
+    FileTreeV1CollectionSanitizationStrategy,
+    FileTreeV1KeySanitizationStrategy,
+)
+
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+from fastmcp.client.transports import SSETransport, StreamableHttpTransport
+from fastmcp.server import create_proxy
+from fastmcp.server.transforms import GetToolNext, Transform
+from fastmcp.tools import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+RemoteTransport = Literal["http", "sse"]
+AuthMode = Literal["oauth", "none"]
+ENV_VAR_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+@dataclass(frozen=True)
+class RemoteConfig:
+    url: str
+    headers: dict[str, str]
+    transport: RemoteTransport
+    auth: AuthMode | None
+    callback_port: int | None
+    callback_host: str
+    callback_timeout: float
+    storage_dir: Path
+    ignore_tools: tuple[str, ...]
+    show_banner: bool
+    log_level: str | None
+
+
+class IgnoreTools(Transform):
+    def __init__(self, patterns: Sequence[str]) -> None:
+        self.patterns = tuple(patterns)
+
+    def _matches(self, name: str) -> bool:
+        return any(fnmatch.fnmatchcase(name, pattern) for pattern in self.patterns)
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [tool for tool in tools if not self._matches(tool.name)]
+
+    async def get_tool(
+        self,
+        name: str,
+        call_next: GetToolNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Tool | None:
+        if self._matches(name):
+            return None
+        return await call_next(name, version=version)
+
+
+def parse_header(value: str) -> tuple[str, str]:
+    name, separator, header_value = value.partition(":")
+    if not separator or not name.strip():
+        raise argparse.ArgumentTypeError("Headers must use the format 'Name: Value'.")
+    try:
+        expanded_value = ENV_VAR_PATTERN.sub(
+            lambda match: os.environ[match.group(1)], header_value
+        )
+    except KeyError as exc:
+        raise argparse.ArgumentTypeError(
+            f"Environment variable {exc.args[0]} is not set."
+        ) from exc
+    return name.strip(), expanded_value.strip()
+
+
+def default_storage_dir(resource: str | None = None) -> Path:
+    if config_dir := os.environ.get("FASTMCP_REMOTE_CONFIG_DIR"):
+        base = Path(config_dir).expanduser()
+    else:
+        base = Path.home() / ".fastmcp" / "remote"
+    if resource is None:
+        return base
+    digest = hashlib.sha256(resource.encode()).hexdigest()[:16]
+    return base / "resources" / digest
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fastmcp-remote",
+        description="Bridge a remote MCP server to a local stdio MCP process.",
+    )
+    parser.add_argument("url", help="Remote MCP server URL.")
+    parser.add_argument(
+        "callback_port",
+        nargs="?",
+        type=int,
+        help="OAuth callback port. Defaults to an available local port.",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["http", "sse"],
+        default="http",
+        help="Remote transport. Defaults to http.",
+    )
+    parser.add_argument(
+        "--header",
+        action="append",
+        default=[],
+        type=parse_header,
+        help="Header to send upstream, in 'Name: Value' form. Repeat for multiple headers.",
+    )
+    parser.add_argument(
+        "--auth",
+        choices=["oauth", "none"],
+        default=None,
+        help="Authentication mode. Defaults to OAuth unless Authorization is provided.",
+    )
+    parser.add_argument(
+        "--resource",
+        help="Resource identifier used to isolate OAuth token storage.",
+    )
+    parser.add_argument(
+        "--host",
+        default="localhost",
+        help="OAuth callback hostname. Defaults to localhost.",
+    )
+    parser.add_argument(
+        "--auth-timeout",
+        type=float,
+        default=300.0,
+        help="Seconds to wait for the OAuth callback. Defaults to 300.",
+    )
+    parser.add_argument(
+        "--ignore-tool",
+        action="append",
+        default=[],
+        help="Hide tools matching this glob pattern. Repeat for multiple patterns.",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging.",
+    )
+    parser.add_argument(
+        "--silent",
+        action="store_true",
+        help="Suppress non-critical logs.",
+    )
+    return parser
+
+
+def parse_args(argv: Sequence[str] | None = None) -> RemoteConfig:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    parsed_url = urlparse(args.url)
+    if parsed_url.scheme not in {"http", "https"}:
+        parser.error("The remote MCP server URL must start with http:// or https://.")
+
+    headers = dict(args.header)
+    if args.silent and args.debug:
+        parser.error("--silent and --debug cannot be used together.")
+    if args.auth_timeout <= 0:
+        parser.error("--auth-timeout must be greater than 0.")
+
+    log_level = "DEBUG" if args.debug else None
+    if args.silent:
+        log_level = "CRITICAL"
+
+    return RemoteConfig(
+        url=args.url,
+        headers=headers,
+        transport=args.transport,
+        auth=args.auth,
+        callback_port=args.callback_port,
+        callback_host=args.host,
+        callback_timeout=args.auth_timeout,
+        storage_dir=default_storage_dir(args.resource),
+        ignore_tools=tuple(args.ignore_tool),
+        show_banner=not args.silent,
+        log_level=log_level,
+    )
+
+
+def build_token_storage(storage_dir: Path) -> AsyncKeyValue:
+    storage_dir.mkdir(parents=True, exist_ok=True)
+    return FileTreeStore(
+        data_directory=storage_dir,
+        key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(storage_dir),
+        collection_sanitization_strategy=FileTreeV1CollectionSanitizationStrategy(
+            storage_dir
+        ),
+    )
+
+
+def resolve_auth(config: RemoteConfig) -> OAuth | None:
+    authorization_header = any(
+        name.lower() == "authorization" for name in config.headers
+    )
+    auth_mode = config.auth
+    if auth_mode is None and authorization_header:
+        auth_mode = "none"
+    elif auth_mode is None:
+        auth_mode = "oauth"
+
+    if auth_mode == "none":
+        return None
+
+    return OAuth(
+        token_storage=build_token_storage(config.storage_dir),
+        callback_port=config.callback_port,
+        callback_host=config.callback_host,
+        callback_timeout=config.callback_timeout,
+    )
+
+
+def build_transport(config: RemoteConfig) -> SSETransport | StreamableHttpTransport:
+    auth = resolve_auth(config)
+    if config.transport == "sse":
+        return SSETransport(config.url, headers=config.headers, auth=auth)
+    return StreamableHttpTransport(config.url, headers=config.headers, auth=auth)
+
+
+async def run(config: RemoteConfig) -> None:
+    client = Client(build_transport(config))
+    server = create_proxy(
+        client,
+        name="fastmcp-remote",
+        provider_error_strategy="raise",
+    )
+    if config.ignore_tools:
+        server.add_transform(IgnoreTools(config.ignore_tools))
+    await server.run_async(
+        transport="stdio",
+        show_banner=config.show_banner,
+        log_level=config.log_level,
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    config = parse_args(argv)
+    anyio.run(run, config)

fastmcp_remote-3.4.0/fastmcp_remote/py.typed

@@ -0,0 +1 @@
+

fastmcp_remote-3.4.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "fastmcp-remote"
+dynamic = ["version", "dependencies"]
+description = "A Python stdio bridge for remote MCP servers, powered by FastMCP."
+authors = [{ name = "Jeremiah Lowin" }]
+
+requires-python = ">=3.10"
+readme = "README.md"
+license = "Apache-2.0"
+
+keywords = [
+    "mcp",
+    "fastmcp remote",
+    "mcp remote",
+    "model context protocol",
+    "fastmcp",
+    "stdio",
+    "oauth",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://gofastmcp.com"
+Repository = "https://github.com/PrefectHQ/fastmcp"
+Documentation = "https://gofastmcp.com"
+"Original npm project" = "https://github.com/geelen/mcp-remote"
+
+[project.scripts]
+fastmcp-remote = "fastmcp_remote.cli:main"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["fastmcp_remote"]
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+fallback-version = "0.0.0"
+
+[tool.hatch.metadata.hooks.uv-dynamic-versioning]
+dependencies = [
+    "fastmcp-slim[client,server]=={{ version }}",
+]