DeepResearch MCP server for AI agents

DeepResearch MCP is a powerful research assistant that conducts intelligent, iterative research through web searches, analysis, and comprehensive report generation. It automatically identifies knowledge gaps, extracts content from web sources, and creates detailed, well-structured reports with proper citations.

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?

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

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.