Provides local web search and content fetching capabilities for AI assistants
MCP Web Tools
A Model Context Protocol (MCP) server that provides web search and fetch capabilities for AI assistants like Claude Code.
This is useful when you want your code-generation tool to make web requests directly from your machine, rather than having those requests proxied through an external server you don't control. The MCP server runs locally on your host, so all web requests originate from your own network.
Features
web_search - Search the web using DuckDuckGo
- Returns formatted results with titles, URLs, and snippets
- Configurable result count and region
web_fetch - Fetch and extract content from web pages
- Automatic HTML-to-text conversion (removes scripts, styles, navigation)
- JSON response formatting
- Configurable timeout
Requirements
- Python 3.13+
- uv
Installation
Quick Install (Recommended)
# Clone the repository
git clone <repo-url>
cd mcp-web-tools
# Install globally and configure Claude Code
make install
This will:
- Install
mcp-web-toolsas a global executable viauv tool install - Register the MCP server with Claude Code using
claude mcp add - The executable will be available at
~/.local/bin/mcp-web-tools
Restart Claude Code after installation.
Manual Installation
# Install dependencies
uv sync
# Run directly from project
uv run mcp-web-tools
Makefile Targets
| Target | Description |
|---|---|
make install |
Install globally and configure Claude Code |
make uninstall |
Remove the global installation |
make test |
Run tests with pytest |
make clean |
Remove build artifacts |
Claude Code Configuration
After running make install, you can verify the registration:
claude mcp list
The tools will be available in Claude Code as:
mcp__web-tools__web_searchmcp__web-tools__web_fetch
Manual Registration
If you prefer to register manually:
# User-wide (available in all projects)
claude mcp add --scope user web-tools mcp-web-tools
# Project-local (only current project)
claude mcp add --scope project web-tools mcp-web-tools
Alternative: Run from Project Directory
For development, you can register to run directly from the source:
claude mcp add --scope project web-tools uv run --directory /path/to/mcp-web-tools mcp-web-tools
Tool Reference
web_search
Search the web using DuckDuckGo.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| query | string | Yes | - | The search query |
| max_results | integer | No | 10 | Maximum number of results |
| region | string | No | "wt-wt" | Region for results (e.g., "us-en", "uk-en") |
Example response:
Search results for: python mcp server
1. Building MCP Servers in Python
URL: https://example.com/article
Learn how to build Model Context Protocol servers...
2. MCP Documentation
URL: https://modelcontextprotocol.io/docs
Official documentation for the Model Context Protocol...
web_fetch
Fetch the content of a web page.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| url | string | Yes | - | The URL to fetch |
| timeout | integer | No | 30 | Request timeout in seconds |
Example response:
Content from https://example.com/article:
Building MCP Servers
This guide covers the basics of creating an MCP server...
Development
Running Tests
make test
# Or directly
uv run pytest -v
Project Structure
mcp-web-tools/
src/
mcp_web_tools/
__init__.py # Package metadata
server.py # MCP server implementation
tools.py # Tool implementations (search, fetch)
tests/
test_tools.py # Unit tests
pyproject.toml # Project configuration
Makefile # Install/uninstall automation
Dependencies
- mcp - Model Context Protocol SDK
- ddgs - DuckDuckGo Search API
- httpx - Async HTTP client
- lxml - HTML parsing (optional; falls back to regex-based extraction if not installed)
License
MIT
Tools (2)
web_searchSearch the web using DuckDuckGo and return formatted results with titles, URLs, and snippets.web_fetchFetch and extract clean text content from web pages, removing scripts, styles, and navigation.Configuration
{
"mcpServers": {
"web-tools": {
"command": "mcp-web-tools",
"args": []
}
}
}