Skip to content

Commit a1226d4

Browse files
claude[bot]olaservo
andcommitted
Add host allowlisting and IP blocking to Fetch server
Implements security feature to prevent access to local/internal IP addresses by default. Addresses the security risk mentioned in issue #2317. Key changes: - Block access to private IP ranges (127.0.0.0/8, 10.0.0.0/8, etc.) by default - Add --allowed-hosts argument for domain allowlisting with wildcard support - Add --allow-private-ips flag for development environments - Add --blocked-ip-ranges for custom IP restrictions - Implement socket-level hostname resolution to prevent TOCTOU attacks - Update README with security documentation and configuration examples 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Ola Hungerford <[email protected]>
1 parent fcb550e commit a1226d4

3 files changed

Lines changed: 217 additions & 3 deletions

File tree

‎src/fetch/README.md‎

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,17 @@
22

33
A Model Context Protocol server that provides web content fetching capabilities. This server enables LLMs to retrieve and process content from web pages, converting HTML to markdown for easier consumption.
44

5-
> [!CAUTION]
6-
> 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.
5+
## Security
6+
7+
**By default, this server blocks access to local/internal IP addresses** (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, etc.) to prevent access to internal networks and services. This provides security against potential misuse.
8+
9+
You can customize security settings using the following options:
10+
- `--allowed-hosts`: Specify allowed hostnames/domains (supports wildcards like *.example.com)
11+
- `--allow-private-ips`: Allow access to private/internal IP ranges
12+
- `--blocked-ip-ranges`: Specify additional CIDR ranges to block
13+
14+
> [!TIP]
15+
> For maximum security in production environments, use `--allowed-hosts` to explicitly whitelist only the domains you need to access.
716
817
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.
918

@@ -168,6 +177,44 @@ This can be customized by adding the argument `--user-agent=YourUserAgent` to th
168177

169178
The server can be configured to use a proxy by using the `--proxy-url` argument.
170179

180+
### Security Configuration Examples
181+
182+
**Allow specific domains only:**
183+
```json
184+
{
185+
"mcpServers": {
186+
"fetch": {
187+
"command": "uvx",
188+
"args": ["mcp-server-fetch", "--allowed-hosts", "example.com", "*.github.com", "docs.python.org"]
189+
}
190+
}
191+
}
192+
```
193+
194+
**Allow internal IPs for development (NOT recommended for production):**
195+
```json
196+
{
197+
"mcpServers": {
198+
"fetch": {
199+
"command": "uvx",
200+
"args": ["mcp-server-fetch", "--allow-private-ips"]
201+
}
202+
}
203+
}
204+
```
205+
206+
**Custom blocked IP ranges:**
207+
```json
208+
{
209+
"mcpServers": {
210+
"fetch": {
211+
"command": "uvx",
212+
"args": ["mcp-server-fetch", "--blocked-ip-ranges", "203.0.113.0/24", "198.51.100.0/24"]
213+
}
214+
}
215+
}
216+
```
217+
171218
## Debugging
172219

173220
You can use the MCP inspector to debug the server. For uvx installations:

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

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,33 @@ 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+
"--allowed-hosts",
21+
type=str,
22+
nargs="*",
23+
help="List of allowed hostnames/domains (supports wildcards like *.example.com). If not specified, all hosts are allowed unless blocked by IP restrictions.",
24+
)
25+
parser.add_argument(
26+
"--allow-private-ips",
27+
action="store_true",
28+
help="Allow access to private/internal IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, etc.)",
29+
)
30+
parser.add_argument(
31+
"--blocked-ip-ranges",
32+
type=str,
33+
nargs="*",
34+
help="Custom list of CIDR ranges to block (in addition to or instead of default private ranges)",
35+
)
1936

2037
args = parser.parse_args()
21-
asyncio.run(serve(args.user_agent, args.ignore_robots_txt, args.proxy_url))
38+
asyncio.run(serve(
39+
args.user_agent,
40+
args.ignore_robots_txt,
41+
args.proxy_url,
42+
args.allowed_hosts,
43+
args.allow_private_ips,
44+
args.blocked_ip_ranges,
45+
))
2246

2347

2448
if __name__ == "__main__":

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

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
from typing import Annotated, Tuple
22
from urllib.parse import urlparse, urlunparse
3+
import ipaddress
4+
import socket
35

46
import markdownify
57
import readabilipy.simple_json
@@ -23,6 +25,131 @@
2325
DEFAULT_USER_AGENT_AUTONOMOUS = "ModelContextProtocol/1.0 (Autonomous; +https://github.com/modelcontextprotocol/servers)"
2426
DEFAULT_USER_AGENT_MANUAL = "ModelContextProtocol/1.0 (User-Specified; +https://github.com/modelcontextprotocol/servers)"
2527

28+
# Default blocked IP ranges (local/internal networks)
29+
DEFAULT_BLOCKED_IP_RANGES = [
30+
"127.0.0.0/8", # Loopback
31+
"10.0.0.0/8", # Private Class A
32+
"172.16.0.0/12", # Private Class B
33+
"192.168.0.0/16", # Private Class C
34+
"169.254.0.0/16", # Link-local
35+
"224.0.0.0/4", # Multicast
36+
"::1/128", # IPv6 loopback
37+
"fc00::/7", # IPv6 unique local
38+
"fe80::/10", # IPv6 link-local
39+
]
40+
41+
42+
def is_ip_in_ranges(ip_str: str, ranges: list[str]) -> bool:
43+
"""Check if an IP address is within any of the specified CIDR ranges.
44+
45+
Args:
46+
ip_str: IP address string to check
47+
ranges: List of CIDR range strings
48+
49+
Returns:
50+
True if IP is in any of the ranges, False otherwise
51+
"""
52+
try:
53+
ip = ipaddress.ip_address(ip_str)
54+
for range_str in ranges:
55+
try:
56+
network = ipaddress.ip_network(range_str, strict=False)
57+
if ip in network:
58+
return True
59+
except ValueError:
60+
continue
61+
return False
62+
except ValueError:
63+
return False
64+
65+
66+
def resolve_hostname_to_ips(hostname: str) -> list[str]:
67+
"""Resolve a hostname to its IP addresses.
68+
69+
Args:
70+
hostname: Hostname to resolve
71+
72+
Returns:
73+
List of IP addresses as strings
74+
75+
Raises:
76+
socket.gaierror: If hostname cannot be resolved
77+
"""
78+
try:
79+
# Get both IPv4 and IPv6 addresses
80+
addr_info = socket.getaddrinfo(hostname, None, family=socket.AF_UNSPEC, type=socket.SOCK_STREAM)
81+
ips = list(set(info[4][0] for info in addr_info))
82+
return ips
83+
except socket.gaierror:
84+
raise
85+
86+
87+
async def validate_url_against_allowlist(
88+
url: str,
89+
allowed_hosts: list[str] | None = None,
90+
blocked_ip_ranges: list[str] | None = None,
91+
allow_private_ips: bool = False
92+
) -> None:
93+
"""Validate a URL against host allowlist and IP range restrictions.
94+
95+
Args:
96+
url: URL to validate
97+
allowed_hosts: List of allowed hostnames/domains. If None, all hosts allowed by IP rules
98+
blocked_ip_ranges: List of CIDR ranges to block. If None, uses DEFAULT_BLOCKED_IP_RANGES
99+
allow_private_ips: If True, allows access to private/internal IP ranges
100+
101+
Raises:
102+
McpError: If URL is not allowed
103+
"""
104+
if blocked_ip_ranges is None:
105+
blocked_ip_ranges = DEFAULT_BLOCKED_IP_RANGES if not allow_private_ips else []
106+
107+
parsed = urlparse(url)
108+
hostname = parsed.hostname
109+
110+
if not hostname:
111+
raise McpError(ErrorData(
112+
code=INVALID_PARAMS,
113+
message="Invalid URL: no hostname found"
114+
))
115+
116+
# Check against allowed hosts list if provided
117+
if allowed_hosts is not None:
118+
host_allowed = False
119+
for allowed_host in allowed_hosts:
120+
if allowed_host.startswith('*.'):
121+
# Wildcard domain matching
122+
domain_suffix = allowed_host[2:]
123+
if hostname == domain_suffix or hostname.endswith('.' + domain_suffix):
124+
host_allowed = True
125+
break
126+
elif hostname == allowed_host:
127+
host_allowed = True
128+
break
129+
130+
if not host_allowed:
131+
raise McpError(ErrorData(
132+
code=INTERNAL_ERROR,
133+
message=f"Host '{hostname}' is not in the allowed hosts list"
134+
))
135+
136+
# Resolve hostname to IP addresses and check against blocked ranges
137+
if blocked_ip_ranges:
138+
try:
139+
ips = resolve_hostname_to_ips(hostname)
140+
except socket.gaierror as e:
141+
raise McpError(ErrorData(
142+
code=INTERNAL_ERROR,
143+
message=f"Failed to resolve hostname '{hostname}': {e}"
144+
))
145+
146+
for ip in ips:
147+
if is_ip_in_ranges(ip, blocked_ip_ranges):
148+
raise McpError(ErrorData(
149+
code=INTERNAL_ERROR,
150+
message=f"Access to IP address '{ip}' (resolved from '{hostname}') is blocked as it falls within restricted IP ranges"
151+
))
152+
26153

27154
def extract_content_from_html(html: str) -> str:
28155
"""Extract and convert HTML content to Markdown format.
@@ -182,13 +309,19 @@ async def serve(
182309
custom_user_agent: str | None = None,
183310
ignore_robots_txt: bool = False,
184311
proxy_url: str | None = None,
312+
allowed_hosts: list[str] | None = None,
313+
allow_private_ips: bool = False,
314+
blocked_ip_ranges: list[str] | None = None,
185315
) -> None:
186316
"""Run the fetch MCP server.
187317
188318
Args:
189319
custom_user_agent: Optional custom User-Agent string to use for requests
190320
ignore_robots_txt: Whether to ignore robots.txt restrictions
191321
proxy_url: Optional proxy URL to use for requests
322+
allowed_hosts: Optional list of allowed hostnames/domains (supports wildcards like *.example.com)
323+
allow_private_ips: Whether to allow access to private/internal IP ranges
324+
blocked_ip_ranges: Optional list of custom CIDR ranges to block
192325
"""
193326
server = Server("mcp-fetch")
194327
user_agent_autonomous = custom_user_agent or DEFAULT_USER_AGENT_AUTONOMOUS
@@ -231,6 +364,11 @@ async def call_tool(name, arguments: dict) -> list[TextContent]:
231364
if not url:
232365
raise McpError(ErrorData(code=INVALID_PARAMS, message="URL is required"))
233366

367+
# Validate URL against allowlist and IP restrictions
368+
await validate_url_against_allowlist(
369+
url, allowed_hosts, blocked_ip_ranges, allow_private_ips
370+
)
371+
234372
if not ignore_robots_txt:
235373
await check_may_autonomously_fetch_url(url, user_agent_autonomous, proxy_url)
236374

@@ -262,6 +400,11 @@ async def get_prompt(name: str, arguments: dict | None) -> GetPromptResult:
262400
url = arguments["url"]
263401

264402
try:
403+
# Validate URL against allowlist and IP restrictions
404+
await validate_url_against_allowlist(
405+
url, allowed_hosts, blocked_ip_ranges, allow_private_ips
406+
)
407+
265408
content, prefix = await fetch_url(url, user_agent_manual, proxy_url=proxy_url)
266409
# TODO: after SDK bug is addressed, don't catch the exception
267410
except McpError as e:

0 commit comments

Comments
 (0)