search-mcp: Minimal Web Search MCP Server

A simple, reliable MCP server for web search using DuckDuckGo. No API keys required. Totally vibe-coded in ~25 minutes. Don't trust this app (even if it works for me).

Features

• Single tool: web_search - search the web via DuckDuckGo
• No API keys needed - uses free DuckDuckGo API
• Timeout handling - 10-second timeout per request to prevent hanging
• Minimal dependencies - only mcp and requests
• Proper MCP protocol - correct stdio transport implementation

Installation

cd ~/Code/search-mcp
pip install -e .

Or with uv:

cd ~/Code/search-mcp
uv pip install -e .

Usage

Direct Testing

python search_mcp.py

Then send JSON-RPC requests via stdin:

{"jsonrpc": "2.0", "method": "tools/list", "id": 1}

Amazon Q Configuration

Add to your ~/.config/cursor/mcp.json or Kiro-CLI config:

{
  "mcpServers": {
    "WebSearch": {
      "type": "stdio",
      "command": "python3",
      "args": ["/Users/USERNAME/Code/search-mcp/search_mcp.py"],
      "timeout": 120000,
      "disabled": false
    }
  }
}

Tool: web_search

Parameters:

• query (string, required): The search query
• max_results (integer, optional): Max results to return (default: 5)

Example:

await client.call_tool("web_search", {"query": "Python async programming", "max_results": 3})

Why This Works

1. Correct MCP protocol - properly implements stdio transport with persistent connection
2. Timeout handling - 10-second timeout on requests to prevent Amazon Q hangs
3. Error handling - gracefully handles network errors and timeouts
4. Simple codebase - ~150 lines, easy to debug or modify
5. No external service - uses DuckDuckGo's free API, no rate limiting issues

Troubleshooting

Module not found errors

Make sure you installed with pip install -e .:

python3 venv .venv
source .venv/bin/activate
pip install -e .

Server not responding

Check that the Python path is correct in your config:

which python3
python3 search_mcp.py

Timeout issues

The server has a 10-second timeout per request. If searches are timing out:

• Check your internet connection
• Verify DuckDuckGo is accessible
• Try simpler/shorter search queries

License

MIT