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](https://nodejs.org/) (version 18.x or later recommended)
* [npm](https://www.npmjs.com/) (comes with Node.js) or [Yarn](https://yarnpkg.com/)
## Installation
### Installing via Smithery
To install deep-research-mcp for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@pinkpixel/dev-deep-research-mcp):
```bash
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:
```bash
npx @pinkpixel/deep-research-mcp
```
### Option 2: Global Installation (Optional)
```bash
npm install -g @pinkpixel/deep-research-mcp
```
Then you can run it using:
```bash
deep-research-mcp
```
### Option 3: Local Project Integration or Development
1. Clone the repository (if you want to modify or contribute):
```bash
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:
```bash
npm install
```
## Configuration
The server requires a Tavily API key and can optionally accept a custom documentation prompt.
```json
{
"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):
```env
TAVILY_API_KEY="tvly-YOUR_ACTUAL_API_KEY"
```
* **Directly in command line:**
```bash
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:**
```env
DOCUMENTATION_PROMPT="Your custom, detailed instructions for the LLM on how to generate markdown..."
```
**Or directly in command line:**
```bash
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:**
```env
RESEARCH_OUTPUT_PATH="/path/to/your/research/folder"
```
**Or directly in command line:**
```bash
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:**
```env
SEARCH_TIMEOUT=120
CRAWL_TIMEOUT=300
MAX_SEARCH_RESULTS=10
CRAWL_MAX_DEPTH=2
CRAWL_LIMIT=15
```
**Or directly in command line:**
```bash
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:**
```env
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:
```json
{
"tool": "write-research-file",
"arguments": {
"file_path": "/home/user/research/quantum-computing-report.md",
"content": "# Quantum Computing Research Report
...",
"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:
```bash
npm run dev
```
This uses `nodemon` and `ts-node` to watch for changes and restart the server.
* **Production/Standalone:**
First, build the TypeScript code:
```bash
npm run build
```
Then, start the server:
```bash
npm start
```
* **With NPX or
---
