DeepResearch MCP

📚 Overview

DeepResearch MCP is a powerful research assistant built on the Model Context Protocol (MCP). It conducts intelligent, iterative research on any topic through web searches, analysis, and comprehensive report generation.

🌟 Key Features

Intelligent Topic Exploration - Automatically identifies knowledge gaps and generates focused search queries
Comprehensive Content Extraction - Enhanced web scraping with improved content organization
Structured Knowledge Processing - Preserves important information while managing token usage
Scholarly Report Generation - Creates detailed, well-structured reports with executive summaries, analyses, and visualizations
Complete Bibliography - Properly cites all sources with numbered references
Adaptive Content Management - Automatically manages content to stay within token limits
Error Resilience - Recovers from errors and generates partial reports when full processing isn't possible

🛠️ Architecture

┌────────────────────┐     ┌─────────────────┐     ┌────────────────┐
│                    │     │                 │     │                │
│  MCP Server Layer  ├────►│ Research Service├────►│ Search Service │
│  (Tools & Prompts) │     │ (Session Mgmt)  │     │  (Firecrawl)   │
│                    │     │                 │     │                │
└────────────────────┘     └─────────┬───────┘     └────────────────┘
                                     │
                                     ▼
                           ┌─────────────────┐
                           │                 │
                           │  OpenAI Service │
                           │ (Analysis/Rpt)  │
                           │                 │
                           └─────────────────┘

💻 Installation

Prerequisites

Node.js 18 or higher
OpenAI API key
Firecrawl API key

Setup Steps

Clone the repository

git clone <repository-url>
cd deep-research-mcp

Install dependencies
```
npm install
```

Configure environment variables

cp .env.example .env

Edit the .env file and add your API keys:

OPENAI_API_KEY=sk-your-openai-api-key
FIRECRAWL_API_KEY=your-firecrawl-api-key

Build the project
```
npm run build
```

🚀 Usage

Running the MCP Server

Start the server on stdio for MCP client connections:

npm start

Using the Example Client

Run research on a specific topic with a specified depth:

npm run client "Your research topic" 3

Parameters:

First argument: Research topic or query
Second argument: Research depth (number of iterations, default: 2)
Third argument (optional): "complete" to use the complete-research tool (one-step process)

Example:

npm run client "the impact of climate change on coral reefs" 3 complete

Example Output

The DeepResearch MCP will produce a comprehensive report that includes:

Executive Summary - Concise overview of the research findings
Introduction - Context and importance of the research topic
Methodology - Description of the research approach
Comprehensive Analysis - Detailed examination of the topic
Comparative Analysis - Visual comparison of key aspects
Discussion - Interpretation of findings and implications
Limitations - Constraints and gaps in the research
Conclusion - Final insights and recommendations
Bibliography - Complete list of sources with URLs

🔧 MCP Integration

Available MCP Resources

Resource Path	Description
`research://state/{sessionId}`	Access the current state of a research session
`research://findings/{sessionId}`	Access the collected findings for a session

Available MCP Tools

Tool Name	Description	Parameters
`initialize-research`	Start a new research session	`query`: string, `depth`: number
`execute-research-step`	Execute the next research step	`sessionId`: string
`generate-report`	Create a final report	`sessionId`: string, `timeout`: number (optional)
`complete-research`	Execute the entire research process	`query`: string, `depth`: number, `timeout`: number (optional)

🖥️ Claude Desktop Integration

DeepResearch MCP can be integrated with Claude Desktop to provide direct research capabilities to Claude.

Configuration Steps

Copy the sample configuration

cp claude_desktop_config_sample.json ~/path/to/claude/desktop/config/directory/claude_desktop_config.json

Edit the configuration file

Update the path to point to your installation of deep-research-mcp and add your API keys:

{
  "mcpServers": {
    "deep-research": {
      "command": "node",
      "args": [
        "/absolute/path/to/your/deep-research-mcp/dist/index.js"
      ],
      "env": {
        "FIRECRAWL_API_KEY": "your-firecrawler-api-key",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

Restart Claude Desktop

After saving the configuration, restart Claude Desktop for the changes to take effect.

Using with Claude Desktop

Now you can ask Claude to perform research using commands like:

Can you research the impact of climate change on coral reefs and provide a detailed report?

📋 Sample Client Code

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // Connect to the server
  const transport = new StdioClientTransport({
    command: "node",
    args: ["dist/index.js"]
  });

  const client = new Client({ name: "deep-research-client", version: "1.0.0" });
  await client.connect(transport);

  // Initialize research
  const initResult = await client.callTool({
    name: "initialize-research",
    arguments: {
      query: "The impact of artificial intelligence on healthcare",
      depth: 3
    }
  });
  
  // Parse the response to get sessionId
  const { sessionId } = JSON.parse(initResult.content[0].text);
  
  // Execute steps until complete
  let currentDepth = 0;
  while (currentDepth < 3) {
    const stepResult = await client.callTool({
      name: "execute-research-step",
      arguments: { sessionId }
    });
    
    const stepInfo = JSON.parse(stepResult.content[0].text);
    currentDepth = stepInfo.currentDepth;
    
    console.log(`Completed step ${stepInfo.currentDepth}/${stepInfo.maxDepth}`);
  }
  
  // Generate final report with timeout
  const report = await client.callTool({
    name: "generate-report",
    arguments: { 
      sessionId,
      timeout: 180000 // 3 minutes timeout
    }
  });
  
  console.log("Final Report:");
  console.log(report.content[0].text);
}

main().catch(console.error);

🔍 Troubleshooting

Common Issues

Token Limit Exceeded: For very large research topics, you may encounter OpenAI token limit errors. Try:
- Reducing the research depth
- Using more specific queries
- Breaking complex topics into smaller sub-topics
Timeout Errors: For complex research, the process may time out. Solutions:
- Increase the timeout parameters in tool calls
- Use the complete-research tool with a longer timeout
- Process research in smaller chunks
API Rate Limits: If you encounter rate limit errors from OpenAI or Firecrawl:
- Implement a delay between research steps
- Use an API key with higher rate limits
- Retry with exponential backoff

📝 License

ISC

🙏 Acknowledgements

Built with Model Context Protocol
Powered by OpenAI and Firecrawl