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:

1. Install mcp-web-tools as a global executable via uv tool install
2. Register the MCP server with Claude Code using claude mcp add
3. 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_search
• mcp__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