Researcher Server

A Model Context Protocol (MCP) server that researches answers to user questions using full DuckDuckGo web search, DuckDuckGo news search, and Wikipedia. Connect it to any MCP-capable client (LM Studio, Claude Desktop, VS Code, etc.) to give a local LLM web-research abilities with current-events coverage.

Tools Provided

Tool	Description
research(query)	Full research report — classifies the query and mixes sources: news queries get dated recent articles, factual questions get a Wikipedia summary plus corroborating web sources and related news, everything else gets full web results
search(query, max_results?)	Raw web search results (title, URL, snippet)
news(query, timelimit?, max_results?)	Recent news articles with publication date and source name; timelimit is d/w/m (day/week/month)
extract(url)	Fetches a URL and returns its readable text (HTML parsed with BeautifulSoup)
get_current_time(location_hint?)	Current date and time

Transports

The server picks its transport from the MCP_TRANSPORT environment variable:

• stdio (default) — for MCP clients that launch the server directly
• streamable-http — network mode; listens on MCP_HOST:MCP_PORT (default 0.0.0.0:8000) at the /mcp path. This is what docker-compose.yml uses.

Quick Start (Docker, recommended)

cd "d:/Local Development/Researcher MCP Server"
docker compose up -d --build

The server is then available to MCP clients at http://localhost:8000/mcp.

Check status and logs:

docker compose ps
docker compose logs -f researcher

Quick Start (Python, stdio)

pip install -r requirements.txt

Then configure your MCP client to launch it — for example in an mcp.json-style config:

{
  "mcpServers": {
    "researcher": {
      "command": "python",
      "args": ["d:/Local Development/Researcher MCP Server/researcher_server.py"]
    }
  }
}

Don't run python researcher_server.py standalone and expect an HTTP port — in stdio mode the client launches and owns the process. For HTTP mode outside Docker, set the env vars first:

$env:MCP_TRANSPORT = "streamable-http"; python researcher_server.py

Connecting LM Studio

See LM_STUDIO_SETUP.md (both methods) and LM_STUDIO_DOCKER_SETUP.md (Docker walkthrough). The short version — in LM Studio 0.3.17+, edit mcp.json via Chat → Program sidebar → Install → Edit mcp.json:

{
  "mcpServers": {
    "researcher": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

How It Works

User question
      ↓
MCP client (LM Studio, Claude, ...) calls the `research` tool
      ↓
Query classification (news / factual / general)
      ↓
Sources queried in parallel:
  - DuckDuckGo web search (full index, via ddgs)
  - DuckDuckGo news search (dated articles with sources)
  - Wikipedia API (encyclopedic summaries)
      ↓
Formatted research report with dates and source URLs → back to the client

Dependencies

• mcp — official MCP Python SDK (FastMCP server)
• httpx — async HTTP client for Wikipedia and page extraction
• ddgs — DuckDuckGo web and news search
• beautifulsoup4 — HTML parsing for page extraction

Troubleshooting

Container exits immediately

Make sure MCP_TRANSPORT=streamable-http is set (docker-compose.yml does this). Without it the server runs in stdio mode and exits as soon as stdin closes — which is immediately, in a detached container.

Client can't connect over HTTP

• Confirm the container is up: docker compose ps
• The endpoint is http://localhost:8000/mcp — the /mcp path is required
• curl http://localhost:8000/mcp returning a JSON-RPC error object means the server is up (a bare GET is expected to be rejected)

Empty or thin search results

• Check internet connectivity from where the server runs
• DuckDuckGo occasionally rate-limits heavy usage; wait a moment and retry

License

MIT License - See LICENSE file for details.