Skip to main content
Glama
Sign In
enesjakozh

DeepResearch MCP

by ameeralns
GitHub
TypeScript
1
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Integrations

  • Uses environment variables for configuration of API keys and other settings, with support for .env files

  • Runs on Node.js as the underlying runtime environment, requiring Node.js 18 or higher for operation

  • Leverages OpenAI for analysis and report generation as part of the research workflow, processing collected information into structured knowledge

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

  1. Clone the repository
    git clone <repository-url> cd deep-research-mcp
  2. Install dependencies
    npm install
  3. 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
  4. 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 PathDescription
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 NameDescriptionParameters
initialize-researchStart a new research sessionquery: string, depth: number
execute-research-stepExecute the next research stepsessionId: string
generate-reportCreate a final reportsessionId: string, timeout: number (optional)
complete-researchExecute the entire research processquery: 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

  1. Copy the sample configuration
    cp claude_desktop_config_sample.json ~/path/to/claude/desktop/config/directory/claude_desktop_config.json
  2. Edit the configuration fileUpdate 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" } } } }
  3. Restart Claude DesktopAfter saving the configuration, restart Claude Desktop for the changes to take effect.
  4. Using with Claude DesktopNow 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

You must be authenticated.

A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

Tools

A powerful research assistant that conducts intelligent, iterative research through web searches, analysis, and comprehensive report generation on any topic.

  1. 📚 Overview
    1. 🌟 Key Features
  2. 🛠️ Architecture
    1. 💻 Installation
      1. Prerequisites
      2. Setup Steps
    2. 🚀 Usage
      1. Running the MCP Server
      2. Using the Example Client
      3. Example Output
    3. 🔧 MCP Integration
      1. Available MCP Resources
      2. Available MCP Tools
    4. 🖥️ Claude Desktop Integration
      1. Configuration Steps
    5. 📋 Sample Client Code
      1. 🔍 Troubleshooting
        1. Common Issues
      2. 📝 License
        1. 🙏 Acknowledgements

          Appeared in Searches

          ID: fstxi0xu1t