Skip to content

Commit a837007

Browse files
authored
Merge pull request #5033 from modelcontextprotocol/v2/fix/4838-fetch-ssrf-guard
fix(fetch): refuse private, loopback and metadata addresses by default (#4838)
2 parents 08314e7 + e577bb0 commit a837007

7 files changed

Lines changed: 356 additions & 24 deletions

File tree

‎scripts/smoke-servers.mjs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,9 @@ export const SERVERS = [
150150
name: "fetch",
151151
language: "py",
152152
transports: ["stdio"],
153+
// fetch refuses loopback addresses by default (#4838); the smoke page is
154+
// on loopback, so the guard is turned off for it.
155+
args: () => ["--allow-private-ips"],
153156
// The loopback page must not be routed through a proxy the developer has
154157
// configured for real traffic.
155158
env: () => ({

‎src/fetch/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ Requires MCP Python SDK 1.x (`mcp>=1.29.0,<2`). SDK 2.0 renamed APIs this server
1010

1111
> [!CAUTION]
1212
> This server can access local/internal IP addresses and may represent a security risk. Exercise caution when using this MCP server to ensure this does not expose any sensitive data.
13+
>
14+
> By default the server refuses to fetch private, loopback, link-local and other non-public addresses, including cloud metadata endpoints such as `169.254.169.254`, and checks every redirect hop the same way. The `--allow-private-ips` argument turns this guard off; see [Customization - Private addresses](#customization---private-addresses). The guard checks the addresses a hostname resolves to before each request, so it does not protect against DNS rebinding between that check and the connection, and a hostname the server cannot resolve itself (one only a proxy can resolve) is not checked.
1315
1416
The fetch tool will truncate the response, but by using the `start_index` argument, you can specify where to start the content extraction. This lets models read a webpage in chunks, until they find the information they need.
1517

@@ -156,6 +158,17 @@ By default, the server will obey a websites robots.txt file if the request came
156158
the request was user initiated (via a prompt). This can be disabled by adding the argument `--ignore-robots-txt` to the
157159
`args` list in the configuration.
158160

161+
### Customization - Private addresses
162+
163+
By default, the server refuses any request, including a redirect hop or a robots.txt fetch, whose host resolves to an
164+
address that is not globally routable: loopback (`127.0.0.0/8`, `::1`), private (`10.0.0.0/8`, `172.16.0.0/12`,
165+
`192.168.0.0/16`, `fc00::/7`), link-local (`169.254.0.0/16`, `fe80::/10`), shared address space (`100.64.0.0/10`),
166+
multicast, unspecified, documentation and the other IANA special-purpose ranges. A hostname is refused if any one of its addresses is in those ranges.
167+
The client receives an error naming the refused address.
168+
169+
To fetch from local or internal hosts (a development server, an intranet page), add the argument
170+
`--allow-private-ips` to the `args` list in the configuration.
171+
159172
### Customization - User-agent
160173

161174
By default, depending on if the request came from the model (via a tool), or was user initiated (via a prompt), the

‎src/fetch/src/mcp_server_fetch/__init__.py‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,21 @@ def main():
1616
help="Ignore robots.txt restrictions",
1717
)
1818
parser.add_argument("--proxy-url", type=str, help="Proxy URL to use for requests")
19+
parser.add_argument(
20+
"--allow-private-ips",
21+
action="store_true",
22+
help="Allow fetching private, loopback and link-local addresses (refused by default)",
23+
)
1924

2025
args = parser.parse_args()
21-
asyncio.run(serve(args.user_agent, args.ignore_robots_txt, args.proxy_url))
26+
asyncio.run(
27+
serve(
28+
args.user_agent,
29+
args.ignore_robots_txt,
30+
args.proxy_url,
31+
args.allow_private_ips,
32+
)
33+
)
2234

2335

2436
if __name__ == "__main__":

‎src/fetch/src/mcp_server_fetch/server.py‎

Lines changed: 140 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
1+
import asyncio
2+
import ipaddress
13
import os
2-
from typing import TYPE_CHECKING, Annotated, Tuple
4+
import socket
5+
from typing import Annotated, Tuple
36
from importlib.metadata import version
47
from urllib.parse import urlparse, urlunparse
58

9+
import httpx
610
import markdownify
711
import readabilipy.simple_json
812
from mcp.shared.exceptions import McpError
@@ -22,9 +26,6 @@
2226
from protego import Protego
2327
from pydantic import BaseModel, Field, AnyUrl
2428

25-
if TYPE_CHECKING:
26-
from httpx import AsyncClient
27-
2829
# The version this server reports in serverInfo, read from the installed
2930
# distribution's metadata (pyproject.toml) so it cannot drift from the
3031
# published version (#360). Without it the SDK reports its own `mcp` version.
@@ -34,6 +35,113 @@
3435
DEFAULT_USER_AGENT_MANUAL = "ModelContextProtocol/1.0 (User-Specified; +https://github.com/modelcontextprotocol/servers)"
3536

3637

38+
async def _resolve_host(host: str) -> list[str]:
39+
"""Resolve ``host`` to every address the OS would hand the connector.
40+
41+
getaddrinfo also parses IP literals, including the shorthand forms such as
42+
``2130706433`` and ``127.1`` that a connector accepts as loopback.
43+
"""
44+
infos = await asyncio.get_running_loop().getaddrinfo(host, None)
45+
return [str(info[4][0]) for info in infos]
46+
47+
48+
# IANA special-purpose ranges that are not public destinations. ``is_global``
49+
# covers most of them, but its tables were corrected only in recent releases
50+
# (3.13, and patch releases of 3.11 and 3.12: before them 192.0.0.0/24 and
51+
# 64:ff9b:1::/48, for example, read as global), so the ranges are listed here
52+
# too, to give the same answer on every supported Python.
53+
_NON_PUBLIC_NETWORKS = tuple(
54+
ipaddress.ip_network(network)
55+
for network in (
56+
"0.0.0.0/8",
57+
"10.0.0.0/8",
58+
"100.64.0.0/10",
59+
"127.0.0.0/8",
60+
"169.254.0.0/16",
61+
"172.16.0.0/12",
62+
"192.0.0.0/24",
63+
"192.0.2.0/24",
64+
"192.88.99.0/24",
65+
"192.168.0.0/16",
66+
"198.18.0.0/15",
67+
"198.51.100.0/24",
68+
"203.0.113.0/24",
69+
"240.0.0.0/4",
70+
"::/128",
71+
"::1/128",
72+
"64:ff9b:1::/48",
73+
"100::/64",
74+
"2001::/23",
75+
"2001:db8::/32",
76+
"2002::/16",
77+
"fc00::/7",
78+
"fe80::/10",
79+
)
80+
)
81+
82+
83+
# Globally reachable assignments inside the ranges above (anycast services
84+
# and the like), matching the exceptions in current CPython's tables.
85+
_PUBLIC_EXCEPTIONS = tuple(
86+
ipaddress.ip_network(network)
87+
for network in (
88+
"192.0.0.9/32",
89+
"192.0.0.10/32",
90+
"2001:1::1/128",
91+
"2001:1::2/128",
92+
"2001:3::/32",
93+
"2001:4:112::/48",
94+
"2001:20::/28",
95+
"2001:30::/28",
96+
)
97+
)
98+
99+
100+
def _is_public_address(address: str) -> bool:
101+
"""True when ``address`` is a globally routable unicast address.
102+
103+
Refused: loopback, RFC 1918, link-local (169.254.0.0/16, which holds most
104+
cloud metadata endpoints), shared address space (100.64.0.0/10, which holds
105+
Alibaba Cloud's 100.100.100.200), unique local IPv6 (AWS's fd00:ec2::254),
106+
multicast, unspecified, documentation and other special-purpose ranges.
107+
"""
108+
ip = ipaddress.ip_address(address)
109+
if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
110+
ip = ip.ipv4_mapped
111+
if any(ip in network for network in _PUBLIC_EXCEPTIONS):
112+
return True
113+
if any(ip in network for network in _NON_PUBLIC_NETWORKS):
114+
return False
115+
return ip.is_global and not ip.is_multicast
116+
117+
118+
async def _refuse_private_destination(request: httpx.Request) -> None:
119+
"""httpx request hook: refuse a request whose host is not a public address.
120+
121+
httpx runs request hooks before every request it sends, redirect hops
122+
included, so a public URL cannot bounce the fetch to an internal one.
123+
"""
124+
host = request.url.host
125+
if not host:
126+
return # httpx rejects a URL with no host itself.
127+
try:
128+
addresses = await _resolve_host(host)
129+
except socket.gaierror:
130+
# Unresolvable here: a direct connection fails on its own, and a proxy
131+
# resolves the name on its side.
132+
return
133+
for address in addresses:
134+
if not _is_public_address(address):
135+
raise McpError(
136+
ErrorData(
137+
code=INVALID_PARAMS,
138+
message=f"Refused to fetch {request.url}: {host} resolves to {address}, "
139+
"which is not a public address. Start the server with "
140+
"--allow-private-ips to allow private, loopback and link-local addresses.",
141+
)
142+
)
143+
144+
37145
def extract_content_from_html(html: str) -> str:
38146
"""Extract and convert HTML content to Markdown format.
39147
@@ -109,17 +217,15 @@ def normalize_proxy_env() -> None:
109217
os.environ[name] = normalize_proxy_url(value)
110218

111219

112-
def make_client(proxy_url: str | None) -> "AsyncClient":
220+
def make_client(proxy_url: str | None) -> httpx.AsyncClient:
113221
"""Build the httpx client, turning a bad proxy setting into a tool error.
114222
115223
httpx validates the proxy (``--proxy-url`` or the proxy environment
116224
variables) when the client is constructed, before any request, so this
117225
failure is not an ``HTTPError``.
118226
"""
119-
from httpx import AsyncClient
120-
121227
try:
122-
return AsyncClient(proxy=proxy_url)
228+
return httpx.AsyncClient(proxy=proxy_url)
123229
except (ValueError, ImportError) as e:
124230
raise McpError(
125231
ErrorData(
@@ -132,7 +238,10 @@ def make_client(proxy_url: str | None) -> "AsyncClient":
132238

133239

134240
async def check_may_autonomously_fetch_url(
135-
url: str, user_agent: str, proxy_url: str | None = None
241+
url: str,
242+
user_agent: str,
243+
proxy_url: str | None = None,
244+
allow_private_ips: bool = False,
136245
) -> None:
137246
"""
138247
Check if the URL can be fetched by the user agent according to the robots.txt file.
@@ -143,6 +252,8 @@ async def check_may_autonomously_fetch_url(
143252
robot_txt_url = get_robots_txt_url(url)
144253

145254
async with make_client(proxy_url) as client:
255+
if not allow_private_ips:
256+
client.event_hooks = {"request": [_refuse_private_destination]}
146257
try:
147258
response = await client.get(
148259
robot_txt_url,
@@ -185,14 +296,20 @@ async def check_may_autonomously_fetch_url(
185296

186297

187298
async def fetch_url(
188-
url: str, user_agent: str, force_raw: bool = False, proxy_url: str | None = None
299+
url: str,
300+
user_agent: str,
301+
force_raw: bool = False,
302+
proxy_url: str | None = None,
303+
allow_private_ips: bool = False,
189304
) -> Tuple[str, str]:
190305
"""
191306
Fetch the URL and return the content in a form ready for the LLM, as well as a prefix string with status information.
192307
"""
193308
from httpx import HTTPError
194309

195310
async with make_client(proxy_url) as client:
311+
if not allow_private_ips:
312+
client.event_hooks = {"request": [_refuse_private_destination]}
196313
try:
197314
response = await client.get(
198315
url,
@@ -265,13 +382,16 @@ async def serve(
265382
custom_user_agent: str | None = None,
266383
ignore_robots_txt: bool = False,
267384
proxy_url: str | None = None,
385+
allow_private_ips: bool = False,
268386
) -> None:
269387
"""Run the fetch MCP server.
270388
271389
Args:
272390
custom_user_agent: Optional custom User-Agent string to use for requests
273391
ignore_robots_txt: Whether to ignore robots.txt restrictions
274392
proxy_url: Optional proxy URL to use for requests
393+
allow_private_ips: Allow fetching private, loopback and link-local
394+
addresses, which are refused by default
275395
"""
276396
if proxy_url:
277397
proxy_url = normalize_proxy_url(proxy_url)
@@ -319,11 +439,15 @@ async def call_tool(name, arguments: dict) -> list[TextContent]:
319439

320440
if not ignore_robots_txt:
321441
await check_may_autonomously_fetch_url(
322-
url, user_agent_autonomous, proxy_url
442+
url, user_agent_autonomous, proxy_url, allow_private_ips
323443
)
324444

325445
content, prefix = await fetch_url(
326-
url, user_agent_autonomous, force_raw=args.raw, proxy_url=proxy_url
446+
url,
447+
user_agent_autonomous,
448+
force_raw=args.raw,
449+
proxy_url=proxy_url,
450+
allow_private_ips=allow_private_ips,
327451
)
328452
original_length = len(content)
329453
if args.start_index >= original_length:
@@ -357,7 +481,10 @@ async def get_prompt(name: str, arguments: dict | None) -> GetPromptResult:
357481

358482
try:
359483
content, prefix = await fetch_url(
360-
url, user_agent_manual, proxy_url=proxy_url
484+
url,
485+
user_agent_manual,
486+
proxy_url=proxy_url,
487+
allow_private_ips=allow_private_ips,
361488
)
362489
# TODO: after SDK bug is addressed, don't catch the exception
363490
except McpError as e:

‎src/fetch/tests/harness.py‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,16 @@
77
go through the SDK's validation and error mapping exactly as a client would.
88
- ``web`` replaces ``httpx.AsyncClient`` with one backed by an
99
``httpx.MockTransport``, so no test touches the network. It records every
10-
request and the keyword arguments each client was constructed with.
10+
request and the keyword arguments each client was constructed with. It also
11+
replaces the server's DNS lookup (``_resolve_host``) with ``FakeWeb.dns``:
12+
a hostname listed there resolves to its addresses, an IP literal resolves to
13+
itself, and any other name resolves to ``PUBLIC_IP``.
1114
"""
1215

1316
from __future__ import annotations
1417

18+
import ipaddress
19+
import socket
1520
import tempfile
1621
from contextlib import asynccontextmanager
1722
from dataclasses import dataclass, field
@@ -30,6 +35,10 @@
3035

3136
Responder = Union[httpx.Response, Callable[[httpx.Request], httpx.Response]]
3237

38+
# A globally routable address (documentation ranges are not global, so they
39+
# would be refused by the private-address guard).
40+
PUBLIC_IP = "93.184.215.14"
41+
3342

3443
@dataclass
3544
class FakeWeb:
@@ -38,6 +47,9 @@ class FakeWeb:
3847
routes: dict[str, Responder] = field(default_factory=dict)
3948
requests: list[httpx.Request] = field(default_factory=list)
4049
client_kwargs: list[dict[str, Any]] = field(default_factory=list)
50+
# hostname -> addresses; an empty list makes the name unresolvable.
51+
dns: dict[str, list[str]] = field(default_factory=dict)
52+
lookups: list[str] = field(default_factory=list)
4153

4254
def add(self, url: str, response: Responder) -> None:
4355
self.routes[url] = response
@@ -54,6 +66,17 @@ def handle(self, request: httpx.Request) -> httpx.Response:
5466
def urls(self) -> list[str]:
5567
return [str(r.url) for r in self.requests]
5668

69+
async def resolve(self, host: str) -> list[str]:
70+
self.lookups.append(host)
71+
try:
72+
return [str(ipaddress.ip_address(host))]
73+
except ValueError:
74+
pass
75+
addresses = self.dns.get(host, [PUBLIC_IP])
76+
if not addresses:
77+
raise socket.gaierror(socket.EAI_NONAME, "Name or service not known")
78+
return addresses
79+
5780

5881
@pytest.fixture
5982
def web(monkeypatch: pytest.MonkeyPatch) -> FakeWeb:
@@ -71,6 +94,7 @@ def factory(**kwargs: Any) -> httpx.AsyncClient:
7194
# server.py imports AsyncClient from httpx inside each function, so
7295
# patching the attribute on the httpx module is what it picks up.
7396
monkeypatch.setattr(httpx, "AsyncClient", factory)
97+
monkeypatch.setattr(server_module, "_resolve_host", fake.resolve)
7498
return fake
7599

76100

0 commit comments

Comments
 (0)