Open Deep Research MCP

The deep-research-mcp server generates comprehensive research reports that include structured analysis and source evaluation. Each source cited in a report is accompanied by a Reliability score (typically on a scale from 0.0 to 1.0) and a qualitative justification. This allows users to assess the credibility of the information provided in the final report.

Example source entry structure:

• URL: The direct link to the source.
• Reliability: A numerical score (e.g., 0.60) representing the assessed trustworthiness.
• Justification: A prose explanation of why that specific score was assigned (e.g., noting commercial bias, lack of editorial oversight, or domain expertise).
• Title: The title of the webpage or document.

The exampleout.md file demonstrates the structure of the research output generated by the deep-research-mcp server. Each research finding is presented as a list item containing:

1. URL: The direct link to the source material.
2. Reliability Score: A numerical value (e.g., 0.85, 0.80) representing the assessed trustworthiness of the source.
3. Reliability Justification: A qualitative explanation of why the source was assigned that score, considering factors like editorial standards, domain expertise, commercial bias, and peer-review status.
4. Title: The title of the specific article or document found.

This structured data allows users to evaluate the credibility of the information used to compile the final report.

Model selection behavior depends on how you are interacting with the server:

• CLI Mode: You will be prompted interactively for the provider and model (e.g., entering openai and then gpt-5.2).
• MCP/HTTP Mode: Pass the model directly using the format provider:model or provider/model (e.g., openai:gpt-5.2).

To avoid using the Firecrawl API, you can run a local instance of Firecrawl. This is a free option that allows you to use a local scraping backend.

1. Clone and set up a local Firecrawl instance (e.g., using the localfirecrawl fork which uses searXNG as the search backend).
2. Update your .env.local to point to the local instance:

FIRECRAWL_BASE_URL="http://localhost:3002"

To get started with the Open Deep Research MCP Server, clone the repository, install dependencies, set up your environment variables, and build the project.

1. Clone and Install

git clone https://github.com/Ozamatash/deep-research
cd deep-research
npm install

2. Configure Environment

Copy the example environment file to .env.local to manage your API keys and configurations.

cp .env.example .env.local

3. Build and Run

Build the server using npm:

npm run build

To run the CLI version:

npm run start

To run as a remote server via Streamable HTTP (runs on http://localhost:3000/mcp without session management):

npm run start:http

To prevent runaway costs during deep research, you can pass a tokenBudget (number) or a budgetState object to deepResearch. The engine tracks usedTokens and sets a reached: true flag when the limit is hit, causing the engine to stop further recursive steps and return the current findings.

BudgetState structure:

• tokenBudget?: number
• usedTokens: number
• reached: boolean

You can track research flows, queries, and results by integrating Langfuse. If no keys are provided, the application functions normally without observability.

Add the following to your .env.local:

• LANGFUSE_PUBLIC_KEY
• LANGFUSE_SECRET_KEY

LANGFUSE_PUBLIC_KEY="your_langfuse_public_key"
LANGFUSE_SECRET_KEY="your_langfuse_secret_key"

You can run the deep-research service using Docker Compose. The configuration expects an environment file named .env.local to be present in the root directory to provide necessary credentials and configurations. The service builds from the current directory and mounts the local project directory to /app/ inside the container to allow for live development/file access.

services:
  deep-research:
    container_name: deep-research
    build: .
    env_file:
      - .env.local
    volumes:
      -  ./:/app/
    tty: true
    stdin_open: true

You can control which models are used by the server by setting the following environment variables: