Skip to content
Back to search

gptr-mcp

MCP server for enabling LLM applications to perform deep research via the MCP protocol

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/assafelovic--gptr-mcp/badge.svg)](/listings/assafelovic--gptr-mcp)

HTML

<a href="/listings/assafelovic--gptr-mcp"><img src="/api/listings/assafelovic--gptr-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Want to use this with Claude Desktop right away?** Here's the fastest path:

1. **Install dependencies:**

   git clone https://github.com/assafelovic/gptr-mcp.git
   pip install -r requirements.txt

2. **Set up your Claude Desktop config** at `~/Library/Application Support/Claude/claude_desktop_config.json`:

   {
     "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"
         }
       }
     }
   }

3. **Restart Claude Desktop** and start researching! πŸŽ‰

For detailed setup instructions, see the [full Claude Desktop Integration section](#-claude-desktop-integration) 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](https://docs.gptr.dev/docs/gpt-researcher/search-engines) - `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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 492 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center" id="top">
  2. <img src="https://github.com/assafelovic/gpt-researcher/assets/13554167/20af8286-b386-44a5-9a83-3be1365139c3" alt="Logo" width="80">
  3. # πŸ” GPT Researcher MCP Server
  4. [![Website](https://img.shields.io/badge/Official%20Website-gptr.dev-teal?style=for-the-badge&logo=world&logoColor=white&color=0891b2)](https://gptr.dev)
  5. [![Documentation](https://img.shields.io/badge/Documentation-DOCS-f472b6?logo=googledocs&logoColor=white&style=for-the-badge)](https://docs.gptr.dev/docs/gpt-researcher/mcp-server/getting-started)
  6. [![Discord Follow](https://dcbadge.vercel.app/api/server/QgZXvJAccX?style=for-the-badge&theme=clean-inverted&?compact=true)](https://discord.gg/QgZXvJAccX)
  7. </div>
  8. ## Why GPT Researcher MCP?
  9. While LLM apps can access web search tools with MCP, **GPT Researcher MCP delivers deep research results.** Standard search tools return raw results requiring manual filtering, often containing irrelevant sources and wasting context window space.
  10. GPT Researcher autonomously explores and validates numerous sources, focusing only on relevant, trusted and up-to-date information. Though slightly slower than standard search (~30 seconds wait), it delivers:
  11. - ✨ Higher quality information
  12. - πŸ“Š Optimized context usage
  13. - πŸ”Ž Comprehensive results
  14. - 🧠 Better reasoning for LLMs
  15. ## πŸ’» Claude Desktop Demo
  16. https://github.com/user-attachments/assets/ef97eea5-a409-42b9-8f6d-b82ab16c52a8
  17. ## πŸš€ Quick Start with Claude Desktop
  18. **Want to use this with Claude Desktop right away?** Here's the fastest path:
  19. 1. **Install dependencies:**
  20. ```bash
  21. git clone https://github.com/assafelovic/gptr-mcp.git
  22. pip install -r requirements.txt
  23. ```
  24. 2. **Set up your Claude Desktop config** at `~/Library/Application Support/Claude/claude_desktop_config.json`:
  25. ```json
  26. {
  27. "mcpServers": {
  28. "gptr-mcp": {
  29. "command": "python",
  30. "args": ["/absolute/path/to/gpt-researcher/gptr-mcp/server.py"],
  31. "env": {
  32. "OPENAI_API_KEY": "your-openai-key-here",
  33. "TAVILY_API_KEY": "your-tavily-key-here"
  34. }
  35. }
  36. }
  37. }
  38. ```
  39. 3. **Restart Claude Desktop** and start researching! πŸŽ‰
  40. For detailed setup instructions, see the [full Claude Desktop Integration section](#-claude-desktop-integration) below.
  41. ### Resources
  42. - `research_resource`: Get web resources related to a given task via research.
  43. ### Primary Tools
  44. - `deep_research`: Performs deep web research on a topic, finding the most reliable and relevant information
  45. - `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](https://docs.gptr.dev/docs/gpt-researcher/search-engines)
  46. - `write_report`: Generate a report based on research results
  47. - `get_research_sources`: Get the sources used in the research
  48. - `get_research_context`: Get the full context of the research
  49. ### Prompts
  50. - `research_query`: Create a research query prompt
  51. ## Prerequisites
  52. Before running the MCP server, make sure you have:
  53. 1. Python 3.11 or higher installed
  54. - **Important**: GPT Researcher >=0.12.16 requires Python 3.11+
  55. 2. API keys for the services you plan to use:
  56. - [OpenAI API key](https://platform.openai.com/api-keys)
  57. - [Tavily API key](https://app.tavily.com)
  58. You can also connect any other web search engines or MCP using GPTR supported retrievers. Check out the [docs here](https://docs.gptr.dev/docs/gpt-researcher/search-engines)
  59. ## βš™οΈ Installation
  60. 1. Clone the GPT Researcher repository:
  61. ```bash
  62. git clone https://github.com/assafelovic/gpt-researcher.git
  63. cd gpt-researcher
  64. ```
  65. 2. Install the gptr-mcp dependencies:
  66. ```bash
  67. cd gptr-mcp
  68. pip install -r requirements.txt
  69. ```
  70. 3. Set up your environment variables:
  71. - Copy the `.env.example` file to create a new file named `.env`:
  72. ```bash
  73. cp .env.example .env
  74. ```
  75. - Edit the `.env` file and add your API keys and configure other settings:
  76. ```bash
  77. OPENAI_API_KEY=your_openai_api_key
  78. TAVILY_API_KEY=your_tavily_api_key
  79. ```
  80. You can also add any other env variable for your GPT Researcher configuration.
  81. ## πŸš€ Running the MCP Server
  82. You can run the MCP server in several ways:
  83. ### Method 1: Directly using Python
  84. ```bash
  85. python server.py
  86. ```
  87. ### Method 2: Using the MCP CLI (if installed)
  88. ```bash
  89. mcp run server.py
  90. ```
  91. ### Method 3: Using Docker (recommended for production)
  92. #### Quick Start
  93. The simplest way to run with Docker:
  94. ```bash
  95. # Build and run with docker-compose
  96. docker-compose up -d
  97. # Or manually:
  98. docker build -t gptr-mcp .
  99. docker run -d \
  100. --name gptr-mcp \
  101. -p 8000:8000 \
  102. --env-file .env \
  103. gptr-mcp
  104. ```
  105. #### For n8n Integration
  106. If you need to connect to an existing n8n network:
  107. ```bash
  108. # First, start the container
  109. docker-compose up -d
  110. # Then connect to your n8n network
  111. docker network connect n8n-mcp-net gptr-mcp
  112. # Or create a shared network first
  113. docker network create n8n-mcp-net
  114. docker network connect n8n-mcp-net gptr-mcp
  115. ```
  116. **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.
  117. 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:
  118. 1. **SSE Endpoint**: Access the Server-Sent Events endpoint at http://localhost:8000/sse to get a session ID
  119. 2. **MCP Communication**: Use the session ID to send MCP messages to http://localhost:8000/messages/?session_id=YOUR_SESSION_ID
  120. 3. **Testing**: Run the test script with `python test_mcp_server.py`
  121. **Important for Docker/n8n Integration:**
  122. - The server binds to `0.0.0.0:8000` to work with Docker containers
  123. - Uses SSE transport for web-based MCP communication
  124. - Session management requires getting a session ID from `/sse` endpoint first
  125. - Each client connection needs a unique session ID for proper communication
  126. ## 🚦 Transport Modes & Best Practices
  127. The GPT Researcher MCP server supports multiple transport protocols and automatically chooses the best one for your environment:
  128. ### Transport Types
  129. | Transport | Use Case | When to Use |
  130. |-----------|----------|-------------|
  131. | **STDIO** | Claude Desktop, Local MCP clients | Default for local development |
  132. | **SSE** | Docker, Web clients, n8n integration | Auto-enabled in Docker |
  133. | **Streamable HTTP** | Modern web deployments | Advanced web deployments |
  134. ### Automatic Detection
  135. The server automatically detects your environment:
  136. ```bash
  137. # Local development (default)
  138. python server.py
  139. # ➜ Uses STDIO transport (Claude Desktop compatible)
  140. # Docker environment
  141. docker run gptr-mcp
  142. # ➜ Auto-detects Docker, uses SSE transport
  143. # Manual override
  144. export MCP_TRANSPORT=sse
  145. python server.py
  146. # ➜ Forces SSE transport
  147. ```
  148. ### Environment Variables
  149. | Variable | Description | Default | Example |
  150. |----------|-------------|---------|---------|
  151. | `MCP_TRANSPORT` | Force specific transport | `stdio` | `sse`, `streamable-http` |
  152. | `DOCKER_CONTAINER` | Force Docker mode | Auto-detected | `true` |
  153. ### Configuration Examples
  154. #### For Claude Desktop (Local)
  155. ```json
  156. // ~/Library/Application Support/Claude/claude_desktop_config.json
  157. {
  158. "mcpServers": {
  159. "gpt-researcher": {
  160. "command": "python",
  161. "args": ["/absolute/path/to/server.py"],
  162. "env": {
  163. "..."
  164. }
  165. }
  166. }
  167. }
  168. ```
  169. #### For Docker/Web Deployment
  170. ```bash
  171. # Set transport explicitly for web deployment
  172. export MCP_TRANSPORT=sse
  173. python server.py
  174. # Or use Docker (auto-detects)
  175. docker-compose up -d
  176. ```
  177. #### For n8n MCP Integration
  178. ```bash
  179. # Use the container name as hostname
  180. docker run --name gptr-mcp -p 8000:8000 gptr-mcp
  181. # In n8n, connect to: http://gptr-mcp:8000/sse
  182. ```
  183. ### Transport Endpoints
  184. When using SSE or HTTP transports:
  185. - **Health Check**: `GET /health`
  186. - **SSE Endpoint**: `GET /sse` (get session ID)
  187. - **MCP Messages**: `POST /messages/?session_id=YOUR_SESSION_ID`
  188. ### Best Practices
  189. 1. **Local Development**: Use default STDIO for Claude Desktop
  190. 2. **Production**: Use Docker with automatic SSE detection
  191. 3. **Testing**: Use health endpoints to verify connectivity
  192. 4. **n8n Integration**: Always use container networking with Docker
  193. 5. **Web Deployment**: Consider Streamable HTTP for modern clients
  194. ## Integrating with Claude
  195. You can integrate your MCP server with Claude using:
  196. **[Claude Desktop Integration](https://docs.gptr.dev/docs/gpt-researcher/mcp-server/claude-integration)** - For using with Claude desktop application on Mac
  197. For detailed instructions, follow the link above.
  198. ## πŸ’» Claude Desktop Integration
  199. To integrate your locally running MCP server with Claude for Mac, you'll need to:
  200. 1. Make sure the MCP server is installed and running
  201. 2. Configure Claude Desktop:
  202. - Locate or create the configuration file at `~/Library/Application Support/Claude/claude_desktop_config.json`
  203. - Add your local GPT Researcher MCP server to the configuration **with environment variables**
  204. - Restart Claude to apply the configuration
  205. ### ⚠️ Important: Environment Variables Required
  206. 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.
  207. ### Configuration Example
  208. ```json
  209. {
  210. "mcpServers": {
  211. "gptr-mcp": {
  212. "command": "python",
  213. "args": ["/absolute/path/to/your/server.py"],
  214. "env": {
  215. "OPENAI_API_KEY": "your-actual-openai-key-here",
  216. "TAVILY_API_KEY": "your-actual-tavily-key-here"
  217. }
  218. }
  219. }
  220. }
  221. ```
  222. ### Security Note
  223. **πŸ”’ Your Claude Desktop config contains sensitive API keys.** Protect it:
  224. ```bash
  225. chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
  226. ```
  227. Never commit this file to version control.
  228. ### Alternative: Environment Variable Script
  229. For better security, create a wrapper script:
  230. **run_gptr_mcp.sh**:
  231. ```bash
  232. #!/bin/bash
  233. source /path/to/your/.env
  234. python /absolute/path/to/server.py
  235. ```
  236. Then use it in Claude Desktop:
  237. ```json
  238. {
  239. "mcpServers": {
  240. "gptr-mcp": {
  241. "command": "/absolute/path/to/run_gptr_mcp.sh"
  242. }
  243. }
  244. }
  245. ```
  246. For complete step-by-step instructions, see the [Claude Desktop Integration guide](https://docs.gptr.dev/docs/gpt-researcher/mcp-server/claude-integration).
  247. ## πŸ“ Example Usage with Claude
  248. ```
  249. User: I'm considering investing in NVIDIA. Can you research the current state of the company, recent stock performance, latest product announcements, and analyst opinions?
  250. Claude: I'll help you research NVIDIA for investment purposes. This will take a moment as I conduct deep research to find the most up-to-date information about their stock performance, recent developments, and expert analysis.
  251. [Claude uses deep_research tool - this takes 30-40 seconds]
  252. Claude: Based on my research, here's a comprehensive analysis of NVIDIA's current state:
  253. ## NVIDIA (NVDA) Current Status
  254. ### Recent Stock Performance
  255. - Current price: $942.89 (as of my research)
  256. - YTD performance: +90.4%
  257. - 52-week range: $460.30 - $974.00
  258. - Market cap: ~$2.32 trillion
  259. ### Recent Key Developments
  260. 1. **Blackwell AI Platform**: At GTC 2024, NVIDIA unveiled the Blackwell architecture, their next-generation AI chip platform promising 4x performance improvement over Hopper. Major cloud providers (AWS, Google, Microsoft) have already committed to integrating Blackwell.
  261. 2. **Q1 FY2025 Earnings (May 2024)**:
  262. - Revenue: $26.0 billion (+262% YoY)
  263. - Data Center revenue: $22.6 billion (+427% YoY)
  264. - Gross margin: 78.4%
  265. - Announced 10-for-1 stock split effective June 7, 2024
  266. 3. **Supply Chain Expansion**: Increased investments in manufacturing capacity with TSMC to address ongoing chip shortages for their high-demand AI GPUs.
  267. ### Analyst Consensus
  268. - Strong Buy consensus with 37 analysts rating it "Buy," 5 "Hold," and 0 "Sell"
  269. - Average price target: $1,042 (post-split adjusted: $104.20)
  270. - Key bull thesis: Continued AI infrastructure spending and NVIDIA's dominant position in AI chips
  271. - Key bear concerns: Valuation, potential competition from AMD, Intel, and custom silicon from tech giants
  272. ### Industry Position
  273. - Dominant in AI GPU market with estimated 80-90% market share
  274. - Expanding ecosystem through CUDA software platform and industry partnerships
  275. - Diversifying beyond chips with DGX Cloud, AI software platforms, and automotive solutions
  276. ```
  277. ## πŸ”§ Troubleshooting
  278. If you encounter issues while running the MCP server:
  279. ### General Issues
  280. 1. **API Keys**: Make sure your API keys are correctly set in the `.env` file
  281. 2. **Python Version**: Check that you're using Python 3.11 or higher (required by gpt-researcher >=0.14.0)
  282. 3. **Dependencies**: Ensure all dependencies are installed correctly: `pip install -r requirements.txt`
  283. 4. **Server Logs**: Check the server logs for error messages
  284. ### Docker Issues
  285. 1. **Container not accessible**:
  286. - Verify the container is running: `docker ps | grep gptr-mcp`
  287. - Check container logs: `docker logs gptr-mcp`
  288. - Confirm the server is binding to 0.0.0.0:8000 (logs should show this)
  289. 2. **n8n Integration Issues**:
  290. - Ensure both containers are on the same Docker network
  291. - Use the container name `gptr-mcp` as the hostname in n8n
  292. - Set the MCP server URL to: `http://gptr-mcp:8000/sse`
  293. 3. **Session ID Issues**:
  294. - The server uses SSE transport which requires session management
  295. - First, get a session ID by connecting to `/sse` endpoint
  296. - Use the session ID in subsequent MCP requests: `/messages/?session_id=YOUR_ID`
  297. - Each client needs its own session ID
  298. ### n8n MCP Integration Steps
  299. 1. **Get Session ID**:
  300. ```bash
  301. curl http://gptr-mcp:8000/sse
  302. # Look for: data: /messages/?session_id=XXXXX
  303. ```
  304. 2. **Initialize MCP**:
  305. ```bash
  306. curl -X POST http://gptr-mcp:8000/messages/?session_id=YOUR_SESSION_ID \
  307. -H "Content-Type: application/json" \
  308. -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {"roots": {"listChanged": true}}, "clientInfo": {"name": "n8n-client", "version": "1.0.0"}}}'
  309. ```
  310. 3. **Call Tools**:
  311. ```bash
  312. curl -X POST http://gptr-mcp:8000/messages/?session_id=YOUR_SESSION_ID \
  313. -H "Content-Type: application/json" \
  314. -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "quick_search", "arguments": {"query": "test"}}}'
  315. ```
  316. ### Testing the Server
  317. Run the included test script to verify functionality:
  318. ```bash
  319. python test_mcp_server.py
  320. ```
  321. This will test:
  322. - SSE connection and session ID retrieval
  323. - MCP initialization
  324. - Tool discovery and execution
  325. ### Claude Desktop Issues
  326. If your MCP server isn't working with Claude Desktop:
  327. 1. **Server not appearing in Claude**:
  328. - Check your `claude_desktop_config.json` syntax is valid JSON
  329. - Ensure you're using **absolute paths** (not relative)
  330. - Verify the path to `server.py` is correct
  331. - Restart Claude Desktop completely
  332. 2. **"OPENAI_API_KEY not found" error**:
  333. - Make sure you added API keys to the `env` section in your config
  334. - Don't forget **both** `OPENAI_API_KEY` and `TAVILY_API_KEY`
  335. - API keys should be the actual keys, not placeholders
  336. 3. **Tools not showing up**:
  337. - Look for the πŸ”§ tools icon in Claude Desktop
  338. - Check that Claude Desktop config file is in the right location:
  339. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  340. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  341. 4. **Python/Permission issues**:
  342. - Make sure Python is accessible from the command line: `python --version`
  343. - Try using full Python path: `"command": "/usr/bin/python3"` or `"command": "python3"`
  344. - Check file permissions on your server.py file
  345. 5. **Still not working?**
  346. - Test the server manually: `python server.py` (should show STDIO transport message)
  347. - Check Claude Desktop logs (if available)
  348. - Try the alternative script method from the integration section above
  349. ## πŸ‘£ Next Steps
  350. - Explore the [MCP protocol documentation](https://docs.anthropic.com/claude/docs/model-context-protocol) to better understand how to integrate with Claude
  351. - Learn about [GPT Researcher's core features](https://docs.gptr.dev/docs/gpt-researcher/getting-started/introduction) to enhance your research capabilities
  352. - Check out the [Advanced Usage](https://docs.gptr.dev/docs/gpt-researcher/mcp-server/advanced-usage) guide for more configuration options
  353. ## πŸ“„ License
  354. This project is licensed under the MIT License - see the LICENSE file for details.
  355. ## πŸ“ž Support / Contact
  356. - [Community Discord](https://discord.gg/QgZXvJAccX)
  357. - Email: assaf.elovic@gmail.com
  358. <p align="right">
  359. <a href="#top">⬆️ Back to Top</a>
  360. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.