Deep Research (Tavily)

Deep Research MCP Server

The Deep Research MCP Server is a Model Context Protocol (MCP) compliant server designed to perform comprehensive web research. It leverages Tavily's powerful Search and new Crawl APIs to gather extensive, up-to-date information on a given topic. The server then aggregates this data along with documentation generation instructions into a structured JSON output, perfectly tailored for Large Language Models (LLMs) to create detailed and high-quality markdown documents.

Features

• Multi-Step Research: Combines Tavily's AI-powered web search with deep content crawling for thorough information gathering.
• Structured JSON Output: Provides well-organized data (original query, search summary, detailed findings per source, and documentation instructions) optimized for LLM consumption.
• Configurable Documentation Prompt: Includes a comprehensive default prompt for generating high-quality technical documentation. This prompt can be:
  • Overridden by setting the DOCUMENTATION_PROMPT environment variable.
  • Further overridden by passing a documentation_prompt argument directly to the tool.
• Configurable Output Path: Specify where research documents and images should be saved through:
  • Environment variable configuration
  • JSON configuration
  • Direct parameter in tool calls
• Granular Control: Offers a wide range of parameters to fine-tune both the search and crawl processes.
• MCP Compliant: Designed to integrate seamlessly into MCP-based AI agent ecosystems.

Prerequisites

• Node.js (version 18.x or later recommended)
• npm (comes with Node.js) or Yarn

Installation

Installing via Smithery

To install deep-research-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @pinkpixel/dev-deep-research-mcp --client claude

Option 1: Using with NPX (Recommended for quick use)

You can run the server directly using npx without a global installation:

npx @pinkpixel/deep-research-mcp

Option 2: Global Installation (Optional)

npm install -g @pinkpixel/deep-research-mcp

Then you can run it using:

deep-research-mcp

Option 3: Local Project Integration or Development

1. Clone the repository (if you want to modify or contribute):

   git clone [https://github.com/your-username/deep-research-mcp.git](https://github.com/your-username/deep-research-mcp.git)
   cd deep-research-mcp
   

2. Install dependencies:

   npm install
   

Configuration

The server requires a Tavily API key and can optionally accept a custom documentation prompt.

{
  "mcpServers": {
    "deep-research": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/deep-research-mcp"
      ],
      "env": {
        "TAVILY_API_KEY": "tvly-YOUR_ACTUAL_API_KEY_HERE", // Required
        "DOCUMENTATION_PROMPT": "Your custom, detailed instructions for the LLM on how to generate markdown documents from the research data...", // Optional - if not provided, the default prompt will be used
        "SEARCH_TIMEOUT": "120", // Optional - timeout in seconds for search requests (default: 60)
        "CRAWL_TIMEOUT": "300", // Optional - timeout in seconds for crawl requests (default: 180)
        "MAX_SEARCH_RESULTS": "10", // Optional - maximum search results to retrieve (default: 7)
        "CRAWL_MAX_DEPTH": "2", // Optional - maximum crawl depth (default: 1)
        "CRAWL_LIMIT": "15", // Optional - maximum URLs to crawl per source (default: 10)
        "FILE_WRITE_ENABLED": "true", // Optional - enable file writing capability (default: false)
        "ALLOWED_WRITE_PATHS": "/home/user/research,/home/user/documents", // Optional - comma-separated allowed directories (default: user home directory)
        "FILE_WRITE_LINE_LIMIT": "300" // Optional - maximum lines per file write operation (default: 200)
      }
    }
  }
}

1. Tavily API Key (Required)

Set the TAVILY_API_KEY environment variable to your Tavily API key.

Methods:

• .env file: Create a .env file in the project root (if running locally for development):

  TAVILY_API_KEY="tvly-YOUR_ACTUAL_API_KEY"
  

• Directly in command line:

  TAVILY_API_KEY="tvly-YOUR_ACTUAL_API_KEY" npx @pinkpixel/deep-research-mcp
  

• System Environment Variable: Set it in your operating system's environment variables.

2. Custom Documentation Prompt (Optional)

You can override the default comprehensive documentation prompt by setting the DOCUMENTATION_PROMPT environment variable.

Methods (in order of precedence):

1. Tool Argument: The documentation_prompt parameter passed when calling the deep-research-tool takes highest precedence
2. Environment Variable: If no parameter is provided in the tool call, the system checks for a DOCUMENTATION_PROMPT environment variable
3. Default Value: If neither of the above are set, the comprehensive built-in default prompt is used

Setting via .env file:

DOCUMENTATION_PROMPT="Your custom, detailed instructions for the LLM on how to generate markdown..."

Or directly in command line:

DOCUMENTATION_PROMPT="Your custom prompt..." TAVILY_API_KEY="tvly-YOUR_KEY" npx @pinkpixel/deep-research-mcp

3. Output Path Configuration (Optional)

You can specify where research documents and images should be saved. If not configured, a default path in the user's Documents folder with a timestamp will be used.

Methods (in order of precedence):

1. Tool Argument: The output_path parameter passed when calling the deep-research-tool takes highest precedence
2. Environment Variable: If no parameter is provided in the tool call, the system checks for a RESEARCH_OUTPUT_PATH environment variable
3. Default Path: If neither of the above are set, a timestamped subfolder in the user's Documents folder is used: ~/Documents/research/YYYY-MM-DDTHH-MM-SS/

Setting via .env file:

RESEARCH_OUTPUT_PATH="/path/to/your/research/folder"

Or directly in command line:

RESEARCH_OUTPUT_PATH="/path/to/your/research/folder" TAVILY_API_KEY="tvly-YOUR_KEY" npx @pinkpixel/deep-research-mcp

4. Timeout and Performance Configuration (Optional)

You can configure timeout and performance settings via environment variables to optimize the tool for your specific use case or deployment environment:

Available Environment Variables:

• SEARCH_TIMEOUT - Timeout in seconds for Tavily search requests (default: 60)
• CRAWL_TIMEOUT - Timeout in seconds for Tavily crawl requests (default: 180)
• MAX_SEARCH_RESULTS - Maximum number of search results to retrieve (default: 7)
• CRAWL_MAX_DEPTH - Maximum crawl depth from base URL (default: 1)
• CRAWL_LIMIT - Maximum number of URLs to crawl per source (default: 10)

Setting via .env file:

SEARCH_TIMEOUT=120
CRAWL_TIMEOUT=300
MAX_SEARCH_RESULTS=10
CRAWL_MAX_DEPTH=2
CRAWL_LIMIT=15

Or directly in command line:

SEARCH_TIMEOUT=120 CRAWL_TIMEOUT=300 TAVILY_API_KEY="tvly-YOUR_KEY" npx @pinkpixel/deep-research-mcp

When to adjust these settings:

• Increase timeouts if you're experiencing timeout errors in LibreChat or other MCP clients
• Decrease timeouts for faster responses when working with simpler queries
• Increase limits for more comprehensive research (but expect longer processing times)
• Decrease limits for faster processing with lighter resource usage

5. File Writing Configuration (Optional)

The server includes a secure file writing tool that allows LLMs to save research findings directly to files. This feature is disabled by default for security reasons.

Security Features:

• File writing must be explicitly enabled via FILE_WRITE_ENABLED=true
• Directory restrictions via ALLOWED_WRITE_PATHS (defaults to user home directory)
• Line limits per write operation to prevent abuse
• Path validation and sanitization
• Automatic directory creation

Configuration:

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

Usage Example: Once enabled, LLMs can use the write-research-file tool to save content:

{
  "tool": "write-research-file",
  "arguments": {
    "file_path": "/home/user/research/quantum-computing-report.md",
    "content": "# Quantum Computing Research Report\n\n...",
    "mode": "rewrite"
  }
}

Security Considerations:

• Only enable file writing in trusted environments
• Use specific directory restrictions rather than allowing system-wide access
• Monitor file operations through server logs
• Consider using read-only directories for sensitive systems

Running the Server

• Development (with auto-reload): If you've cloned the repository and are in the project directory:

  npm run dev
  

  This uses nodemon and ts-node to watch for changes and restart the server.

• Production/Standalone: First, build the TypeScript code:

  npm run build
  

  Then, start the server:

  npm start
  

• **With NPX or

---

README truncated. View full README on GitHub.