Metadata-Version: 2.4
Name: heventure-search-mcp
Version: 1.4.18
Summary: Free, API-key-free web search MCP server — DuckDuckGo, Bing, Google & optional SerpAPI/Tavily
Author: HughesCuit
License: MIT
Project-URL: Homepage, https://github.com/HughesCuit/heventure-search-mcp
Project-URL: Repository, https://github.com/HughesCuit/heventure-search-mcp
Project-URL: Issues, https://github.com/HughesCuit/heventure-search-mcp/issues
Project-URL: Documentation, https://github.com/HughesCuit/heventure-search-mcp#readme
Keywords: mcp,search,web,duckduckgo,bing,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: beautifulsoup4>=4.11.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: socks
Requires-Dist: aiohttp-socks>=0.8.4; extra == "socks"
Provides-Extra: tavily
Requires-Dist: tavily>=1.0.0; extra == "tavily"
Provides-Extra: lxml-parser
Requires-Dist: lxml>=4.9.0; extra == "lxml-parser"

[**中文**](./README_CN.md) | English

---

# MCP Web Search Server

A free, API-key-free web search MCP (Model Context Protocol) server supporting DuckDuckGo, Bing, Google, and optional SerpAPI/Tavily for enhanced search quality.

## Features

- 🔍 **Multi-Engine Search**: DuckDuckGo + Bing + Google (free, no API key required)
- 🔑 **Optional API Keys**: SerpAPI and Tavily for better search quality
- 📄 **Web Content Fetching**: Get text content from any webpage
- 🚀 **Async Processing**: High-performance asyncio-based async handling

## Installation

### PyPI (Recommended)

```bash
pip install heventure-search-mcp
heventure-search-mcp
```

### uvx

```bash
uvx heventure-search-mcp
```

### From Source

```bash
pip install git+https://github.com/HughesCuit/heventure-search-mcp.git
python -m server
```

## Usage

### MCP Client Config

```json
{
  "mcpServers": {
    "web-search": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}
```

### Trae AI

```json
{
  "mcpServers": {
    "heventure-search-mcp": {
      "command": "uvx",
      "args": ["heventure-search-mcp"]
    }
  }
}
```

## Available Tools

### web_search

Search web content with multiple engines.

**Parameters:**
- `query` (string, required): Search query
- `max_results` (integer, optional): Max results (default: 10, range: 1-20)
- `search_engine` (string, optional): Engine choice (default: "both")
  - `"duckduckgo"`: DuckDuckGo only
  - `"bing"`: Bing only
  - `"google"`: Google only
  - `"both"`: DuckDuckGo + Google + Bing

### Optional API Keys (for Enhanced Search)

You can optionally set environment variables to enable paid search engines:

```bash
# SerpAPI (Google search results via API, 100 searches/month free)
export SERPAPI_KEY="your_serpapi_key"

# Tavily (AI-optimized search, 1000 searches/month free)
export TAVILY_API_KEY="your_tavily_api_key"
```

When API keys are configured, they will be automatically used alongside the free engines to improve search quality.

**Example:**
```json
{
  "query": "Python tutorial",
  "max_results": 5,
  "search_engine": "both"
}
```

### get_webpage_content

Get text content from a webpage.

**Parameters:**
- `url` (string, required): Target webpage URL

**Example:**
```json
{
  "url": "https://example.com"
}
```

## Error Handling

- Automatic retry on network failure
- Graceful degradation on parse errors
- User-friendly error messages

## License

MIT License

## Contributing

Issues and Pull Requests are welcome!
