Deep Research

You run the Deep Research MCP Server to perform automated, multi-source web research and generate structured documentation for large language models. It combines Tavily-powered search and crawl capabilities to gather up-to-date information, then outputs a well-organized JSON payload and documentation instructions tailored for creating high-quality markdown documents.

How to use

Use an MCP client to call the deep-research tool and provide a topic or query. The server will perform a Tavily search to discover relevant sources, crawl those sources for detailed content, and return a structured JSON payload that includes the original query, a search summary, crawled content, image references, and instructions for generating final documentation. The tool selection, prompt used for documentation, and the output location are all customizable through tool arguments or environment configuration.

How to install

Prerequisites: install Node.js version 18.x or later and npm (comes with Node.js) or Yarn.

# Quick start with NPX (recommended for quick usage)
npx @pinkpixel/deep-research-mcp

# Alternative: Global installation
npm install -g @pinkpixel/deep-research-mcp
deep-research-mcp

# Development workflow (clone and run locally)
# (Follow these steps if you want to modify or contribute)

Configuration and runtime notes

Configure the server with your Tavily API key and optional customization for the documentation prompt and output paths. The configuration enables you to override the built-in prompt, set timeouts, and specify where to save generated research materials.

{
  "mcpServers": {
    "deep_research": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/deep-research-mcp"
      ],
      "env": {
        "TAVILY_API_KEY": "tvly-YOUR_ACTUAL_API_KEY_HERE",
        "DOCUMENTATION_PROMPT": "Your custom, detailed instructions for the LLM on how to generate markdown documents from the research data...",
        "SEARCH_TIMEOUT": "120",
        "CRAWL_TIMEOUT": "300",
        "MAX_SEARCH_RESULTS": "10",
        "CRAWL_MAX_DEPTH": "2",
        "CRAWL_LIMIT": "15",
        "FILE_WRITE_ENABLED": "true",
        "ALLOWED_WRITE_PATHS": "/home/user/research,/home/user/documents",
        "FILE_WRITE_LINE_LIMIT": "500"
      }
    }
  }
}

Output path and environment variables

You can control where generated documents and images are saved. The tool respects the following precedence: tool argument, environment variable RESEARCH_OUTPUT_PATH, or a timestamped folder in your Documents directory.

{
  "RESEARCH_OUTPUT_PATH": "/path/to/your/research/folder"
}

Security and file writing (optional)

The server includes a secure, optional file-writing capability that lets the LLM save research findings to files. Enable it with FILE_WRITE_ENABLED and restrict write locations with ALLOWED_WRITE_PATHS.

FILE_WRITE_ENABLED=true
ALLOWED_WRITE_PATHS=/home/user/research,/home/user/documents,/tmp/research
FILE_WRITE_LINE_LIMIT=500

Running the server in development and production

Run in development with auto-reload, or build and run for production. Use the commands below to start in your preferred mode.

# Development with auto-reload (if you clone the repo and install dependencies)
npm run dev

# Production/standalone build and start
npm run build
npm start

How it works

An MCP client calls the deep-research tool with a query. The tool performs a Tavily search, crawls the identified sources for deeper content, aggregates results, applies the selected documentation prompt, and returns a single JSON payload that includes the original query, search summary, crawled data, and guidance for generating the markdown document.

Available tools

deep-research-tool

Primary MCP tool that performs Tavily search and crawl, aggregates results, and returns a structured JSON payload with documentation instructions.

write-research-file

Secure tool exposed to save research results to files when FILE_WRITE_ENABLED is true; supports writing content to specified paths with safety checks.