Researcher MCP 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

When a search backend is unavailable (DuckDuckGo rate-limits under heavy use), the tools report that explicitly — research adds a "SOURCES UNAVAILABLE" section and search/news raise an error — so an empty result always means "nothing found" rather than "the lookup failed".

Related MCP server: Search Proxy MCP

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.

Configuration

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

• tzdata — timezone database (slim/Windows images don't ship one)

Running the Tests

The test suite covers the classification, timezone, URL-policy, and formatting logic without touching the network:

pip install -r requirements-dev.txt
pytest -q

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; the report will say "SOURCES UNAVAILABLE" when that happens — wait a moment and retry

Reported time is wrong

Set DEFAULT_TIMEZONE to your IANA zone (e.g. America/Los_Angeles) in docker-compose.yml. Containers run on UTC by default.

extract refuses a URL

Non-public addresses (loopback, 10.x, 192.168.x, 169.254.x) and non-text content types are blocked by design. Set ALLOW_PRIVATE_URLS=1 if you genuinely need to fetch internal pages.

License

MIT License - See LICENSE file for details.