# ddg-mcp-search

A minimal [MCP](https://modelcontextprotocol.io/) server that exposes a single **DuckDuckGo search** tool.  
Use this as a lean starting point for building your own MCP servers with a plugin architecture.

## Features

- **`search` tool** — DuckDuckGo full-text search with region, time-limit, and safe-search options
- Plugin architecture — drop a new `.py` file into `plugins/` and it is auto-discovered on startup
- SSE transport (compatible with Claude Desktop and other MCP clients)

## Requirements

- Python 3.10+
- pip packages listed in `requirements.txt`

## Installation

```bash
git clone https://github.com/ss0832/ddg-mcp-search.git
cd ddg-mcp-search
pip install -r requirements.txt
```

## Usage

```bash
python main.py
```

The server starts on `http://0.0.0.0:9500` by default.

| Environment variable | Default     | Description        |
|----------------------|-------------|--------------------|
| `MCP_HOST`           | `0.0.0.0`   | Bind host          |
| `MCP_PORT`           | `9500`      | Bind port          |

## Connecting to Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ddg-mcp-search": {
      "url": "http://localhost:9500/sse"
    }
  }
}
```

## Tool reference

### `search`

Search the web using DuckDuckGo.

| Parameter    | Type    | Required | Default    | Description                                               |
|--------------|---------|----------|------------|-----------------------------------------------------------|
| `query`      | string  | ✅       | —          | Search query                                              |
| `region`     | string  |          | `jp-jp`    | Region code, e.g. `us-en`, `jp-jp`                       |
| `timelimit`  | string  |          | —          | `d` = past day, `w` = past week, `m` = past month, `y` = past year |
| `safesearch` | string  |          | `moderate` | `on`, `moderate`, or `off`                                |
| `max_results`| integer |          | `20`       | Maximum number of results to return                       |

**Example response:**

```
- DuckDuckGo — Privacy, simplified.
  URL: https://duckduckgo.com
  Snippet: The Internet privacy company that empowers you to seamlessly take control of your personal information online, without any tradeoffs.
```

## Adding new tools

1. Create `plugins/my_tool.py`
2. Define a class inheriting `MCPPlugin` with `get_tools()` and `call_tool()` methods
3. Restart the server — it is discovered automatically

See `plugins/web_search.py` for a complete example.

## License

[MIT](LICENSE) © 2026 ss0832