{
  "mcpServers": {
    "gptr-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/gpt-researcher/gptr-mcp/server.py"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key-here",
        "TAVILY_API_KEY": "your-tavily-key-here"
      }
    }
  }
}

For detailed setup instructions, see the full Claude Desktop Integration section below.

Resources

• research_resource: Get web resources related to a given task via research.

Primary Tools

• deep_research: Performs deep web research on a topic, finding the most reliable and relevant information
• quick_search: Performs a fast web search optimized for speed over quality, returning search results with snippets. Supports any GPTR supported web retriever such as Tavily, Bing, Google, etc... Learn more here
• write_report: Generate a report based on research results
• get_research_sources: Get the sources used in the research
• get_research_context: Get the full context of the research

Prompts

• research_query: Create a research query prompt

Prerequisites

Before running the MCP server, make sure you have:

1. Python 3.11 or higher installed
   • Important: GPT Researcher >=0.12.16 requires Python 3.11+
2. API keys for the services you plan to use:
   • OpenAI API key
   • Tavily API key

You can also connect any other web search engines or MCP using GPTR supported retrievers. Check out the docs here

⚙️ Installation

1. Clone the GPT Researcher repository:

git clone https://github.com/assafelovic/gpt-researcher.git
cd gpt-researcher

2. Install the gptr-mcp dependencies:

cd gptr-mcp
pip install -r requirements.txt

3. Set up your environment variables:
   • Copy the .env.example file to create a new file named .env:

   cp .env.example .env
   

   • Edit the .env file and add your API keys and configure other settings:

   OPENAI_API_KEY=your_openai_api_key
   TAVILY_API_KEY=your_tavily_api_key
   

You can also add any other env variable for your GPT Researcher configuration.

🚀 Running the MCP Server

You can run the MCP server in several ways:

Method 1: Directly using Python

python server.py

Method 2: Using the MCP CLI (if installed)

mcp run server.py

Method 3: Using Docker (recommended for production)

Quick Start

The simplest way to run with Docker:

# Build and run with docker-compose
docker-compose up -d

# Or manually:
docker build -t gptr-mcp .
docker run -d \
  --name gptr-mcp \
  -p 8000:8000 \
  --env-file .env \
  gptr-mcp

For n8n Integration

If you need to connect to an existing n8n network:

# First, start the container
docker-compose up -d

# Then connect to your n8n network
docker network connect n8n-mcp-net gptr-mcp

# Or create a shared network first
docker network create n8n-mcp-net
docker network connect n8n-mcp-net gptr-mcp

Note: The Docker image uses Python 3.11 to meet the requirements of gpt-researcher >=0.12.16. If you encounter errors during the build, ensure you're using the latest Dockerfile from this repository.

Once the server is running, you'll see output indicating that the server is ready to accept connections. You can verify it's working by:

1. SSE Endpoint: Access the Server-Sent Events endpoint at http://localhost:8000/sse to get a session ID
2. MCP Communication: Use the session ID to send MCP messages to http://localhost:8000/messages/?session_id=YOUR_SESSION_ID
3. Testing: Run the test script with python test_mcp_server.py

Important for Docker/n8n Integration:

• The server binds to 0.0.0.0:8000 to work with Docker containers
• Uses SSE transport for web-based MCP communication
• Session management requires getting a session ID from /sse endpoint first
• Each client connection needs a unique session ID for proper communication

🚦 Transport Modes & Best Practices

The GPT Researcher MCP server supports multiple transport protocols and automatically chooses the best one for your environment:

Transport Types

| Transport | Use Case | When to Use | |-----------|----------|-------------| | STDIO | Claude Desktop, Local MCP clients | Default for local development | | SSE | Docker, Web clients, n8n integration | Auto-enabled in Docker | | Streamable HTTP | Modern web deployments | Advanced web deployments |

Automatic Detection

The server automatically detects your environment:

# Local development (default)
python server.py
# ➜ Uses STDIO transport (Claude Desktop compatible)

# Docker environment  
docker run gptr-mcp
# ➜ Auto-detects Docker, uses SSE transport

# Manual override
export MCP_TRANSPORT=sse
python server.py
# ➜ Forces SSE transport

Environment Variables

| Variable | Description | Default | Example | |----------|-------------|---------|---------| | MCP_TRANSPORT | Force specific transport | stdio | sse, streamable-http | | DOCKER_CONTAINER | Force Docker mode | Auto-detected | true |

Configuration Examples

For Claude Desktop (Local)

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "gpt-researcher": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
         "..."
      }
    }
  }
}

For Docker/Web Deployment

# Set transport explicitly for web deployment
export MCP_TRANSPORT=sse
python server.py

# Or use Docker (auto-detects)
docker-compose up -d

For n8n MCP Integration

# Use the container name as hostname
docker run --name gptr-mcp -p 8000:8000 gptr-mcp

# In n8n, connect to: http://gptr-mcp:8000/sse

Transport Endpoints

When using SSE or HTTP transports:

• Health Check: GET /health
• SSE Endpoint: GET /sse (get session ID)
• MCP Messages: POST /messages/?session_id=YOUR_SESSION_ID

Best Practices

1. Local Development: Use default STDIO for Claude Desktop
2. Production: Use Docker with automatic SSE detection
3. Testing: Use health endpoints to verify connectivity
4. n8n Integration: Always use container networking with Docker
5. Web Deployment: Consider Streamable HTTP for modern clients

Integrating with Claude

You can integrate your MCP server with Claude using:

Claude Desktop Integration - For using with Claude desktop application on Mac

For detailed instructions, follow the link above.

💻 Claude Desktop Integration

To integrate your locally running MCP server with Claude for Mac, you'll need to:

1. Make sure the MCP server is installed and running
2. Configure Claude Desktop:
   • Locate or create the configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json
   • Add your local GPT Researcher MCP server to the configuration with environment variables
   • Restart Claude to apply the configuration

⚠️ Important: Environment Variables Required

Claude Desktop launches your MCP server as a separate subprocess, so you must explicitly pass your API keys in the configuration. The server cannot access your shell's environment variables or .env file automatically.

Configuration Example

{
  "mcpServers": {
    "gptr-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/your/server.py"],
      "env": {
        "OPENAI_API_KEY": "your-actual-openai-key-here",
        "TAVILY_API_KEY": "your-actual-tavily-key-here"
      }
    }
  }
}

Security Note

🔒 Your Claude Desktop config contains sensitive API keys. Protect it:

chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

Never commit this file to version control.

Alternative: Environment Variable Script

For bette