Skip to content
Back to search

gpt-researcher

An autonomous agent that conducts deep research on any data using any LLM providers

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/assafelovic/gpt-researcher with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/assafelovic/gpt-researcher'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/assafelovic-gpt-researcher"><img src="/api/listings/assafelovic-gpt-researcher/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.

Extend Claude's deep research capabilities by installing GPT Researcher as a [Claude Skill](https://skills.sh/assafelovic/gpt-researcher/gpt-researcher):

npx skills add assafelovic/gpt-researcher

Once installed, Claude can leverage GPT Researcher's deep research capabilities directly within your conversations.

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 · 379 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center" id="top">
  2. <img src="https://raw.githubusercontent.com/assafelovic/gpt-researcher/main/docs/static/img/gptr-logo-tile.png" alt="GPT Researcher logo" width="80">
  3. ####
  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)
  6. [![Discord](https://img.shields.io/discord/1127851779011391548?logo=discord&logoColor=white&label=Discord&color=34b76a&style=for-the-badge)](https://discord.gg/QgZXvJAccX)
  7. [![PyPI version](https://img.shields.io/pypi/v/gpt-researcher?logo=pypi&logoColor=white&style=flat)](https://badge.fury.io/py/gpt-researcher)
  8. ![GitHub Release](https://img.shields.io/github/v/release/assafelovic/gpt-researcher?style=flat&logo=github)
  9. [![Open In Colab](https://img.shields.io/static/v1?message=Open%20in%20Colab&logo=googlecolab&labelColor=grey&color=yellow&label=%20&style=flat&logoSize=40)](https://colab.research.google.com/github/assafelovic/gpt-researcher/blob/master/docs/docs/examples/pip-run.ipynb)
  10. [![Docker Image Version](https://img.shields.io/docker/v/elestio/gpt-researcher/latest?arch=amd64&style=flat&logo=docker&logoColor=white&color=1D63ED)](https://hub.docker.com/r/gptresearcher/gpt-researcher)
  11. [![Skill](https://img.shields.io/badge/Claude%20Skill-skills.sh-blueviolet?style=flat&logo=anthropic&logoColor=white)](https://skills.sh/assafelovic/gpt-researcher/gpt-researcher)
  12. [![Twitter Follow](https://img.shields.io/twitter/follow/assaf_elovic?style=social)](https://twitter.com/assaf_elovic)
  13. [English](README.md) | [中文](README-zh_CN.md) | [日本語](README-ja_JP.md) | [한국어](README-ko_KR.md) | [Русский](README-ru_RU.md)
  14. </div>
  15. # 🔎 GPT Researcher
  16. **GPT Researcher the first open deep research agent designed for both web and local research on any given task.**
  17. The agent produces detailed, factual, and unbiased research reports with citations. GPT Researcher provides a full suite of customization options to create tailor made and domain specific research agents. GPT Researcher goes well beyond RAG: planner and execution agents break each task into research questions, [decision models](#-smart-context-filtering-with-jev) keep only the context that is actually useful for answering them, [multi-agent](#-multi-agent-assistant) workflows coordinate specialized agents from planning to publication, and [recursive deep research](#-deep-research) explores a topic in both breadth and depth. Research runs in parallel, which keeps it fast, stable and reliable, and reduces misinformation.
  18. **Our mission is to empower individuals and organizations with accurate, unbiased, and factual information through AI.**
  19. ## Why GPT Researcher?
  20. - Objective conclusions for manual research can take weeks, requiring vast resources and time.
  21. - LLMs trained on outdated information can hallucinate, becoming irrelevant for current research tasks.
  22. - Current LLMs have token limitations, insufficient for generating long research reports.
  23. - Limited web sources in existing services lead to misinformation and shallow results.
  24. - Selective web sources can introduce bias into research tasks.
  25. ## Demo
  26. <a href="https://github.com/user-attachments/assets/4d3f26cf-8ccc-413a-b17c-80aa9e1b52d1">
  27. <picture>
  28. <source media="(prefers-reduced-motion: reduce)" srcset="https://github.com/user-attachments/assets/25d92184-c59e-4115-9961-759ada1ec952">
  29. <img src="https://github.com/user-attachments/assets/3a56a008-fcbd-4373-9e40-8d6027120cfb" alt="GPT Researcher turning a question into a cited report" width="800">
  30. </picture>
  31. </a>
  32. ## Install as Claude Skill
  33. Extend Claude's deep research capabilities by installing GPT Researcher as a [Claude Skill](https://skills.sh/assafelovic/gpt-researcher/gpt-researcher):
  34. ```bash
  35. npx skills add assafelovic/gpt-researcher
  36. ```
  37. Once installed, Claude can leverage GPT Researcher's deep research capabilities directly within your conversations.
  38. ## Architecture
  39. The core idea is to utilize 'planner' and 'execution' agents. The planner generates research questions, while the execution agents gather relevant information. The publisher then aggregates all findings into a comprehensive report.
  40. <div align="center">
  41. <img align="center" height="600" src="https://github.com/assafelovic/gpt-researcher/assets/13554167/4ac896fd-63ab-4b77-9688-ff62aafcc527">
  42. </div>
  43. Steps:
  44. * Create a task-specific agent based on a research query.
  45. * Generate questions that collectively form an objective opinion on the task.
  46. * Use a crawler agent for gathering information for each question.
  47. * Summarize and source-track each resource.
  48. * Filter and aggregate summaries into a final research report.
  49. ## Tutorials
  50. - [How it Works](https://docs.gptr.dev/blog/building-gpt-researcher)
  51. - [How to Install](https://www.loom.com/share/04ebffb6ed2a4520a27c3e3addcdde20?sid=da1848e8-b1f1-42d1-93c3-5b0b9c3b24ea)
  52. - [Live Demo](https://www.loom.com/share/6a3385db4e8747a1913dd85a7834846f?sid=a740fd5b-2aa3-457e-8fb7-86976f59f9b8)
  53. ## Features
  54. - 📝 Generate detailed research reports using web and local documents.
  55. - 🖼️ Smart image scraping and filtering for reports.
  56. - 🍌 **AI-generated inline images** using Google Gemini (Nano Banana) for visual illustrations.
  57. - 📜 Generate detailed reports exceeding 2,000 words.
  58. - 🌐 Aggregate over 20 sources for objective conclusions.
  59. - 🎯 Smart context filtering with [Jev](#-smart-context-filtering-with-jev), with no API key or embeddings required by default.
  60. - 🖥️ Frontend available in lightweight (HTML/CSS/JS) and production-ready (NextJS + Tailwind) versions.
  61. - 🔍 JavaScript-enabled web scraping.
  62. - 📂 Maintains memory and context throughout research.
  63. - 📄 Export reports to PDF, Word, and other formats.
  64. ## 📖 Documentation
  65. See the [Documentation](https://docs.gptr.dev/docs/gpt-researcher/getting-started) for:
  66. - Installation and setup guides
  67. - Configuration and customization options
  68. - How-To examples
  69. - Full API references
  70. ## ⚙️ Getting Started
  71. ### Installation
  72. 1. Install Python 3.12 or later. [Guide](https://www.tutorialsteacher.com/python/install-python).
  73. 2. Clone the project and navigate to the directory:
  74. ```bash
  75. git clone https://github.com/assafelovic/gpt-researcher.git
  76. cd gpt-researcher
  77. ```
  78. 3. Set up API keys by exporting them or storing them in a `.env` file.
  79. ```bash
  80. export OPENAI_API_KEY={Your OpenAI API Key here}
  81. export TAVILY_API_KEY={Your Tavily API Key here}
  82. ```
  83. (Optional) For enhanced tracing and observability, you can also set:
  84. ```bash
  85. # export LANGCHAIN_TRACING_V2=true
  86. # export LANGCHAIN_API_KEY={Your LangChain API Key here}
  87. ```
  88. For custom OpenAI-compatible APIs (e.g., local models, other providers), you can also set:
  89. ```bash
  90. export OPENAI_BASE_URL={Your custom API base URL here}
  91. ```
  92. 4. Install dependencies and start the server:
  93. ```bash
  94. pip install -r requirements.txt
  95. python -m uvicorn main:app --reload
  96. ```
  97. Visit [http://localhost:8000](http://localhost:8000) to start.
  98. For other setups (e.g., Poetry or virtual environments), check the [Getting Started page](https://docs.gptr.dev/docs/gpt-researcher/getting-started).
  99. ## Run as PIP package
  100. ```bash
  101. pip install gpt-researcher
  102. ```
  103. ### Example Usage:
  104. ```python
  105. ...
  106. from gpt_researcher import GPTResearcher
  107. query = "why is Nvidia stock going up?"
  108. researcher = GPTResearcher(query=query)
  109. # Conduct research on the given query
  110. research_result = await researcher.conduct_research()
  111. # Write the report
  112. report = await researcher.write_report()
  113. ...
  114. ```
  115. **For more examples and configurations, please refer to the [PIP documentation](https://docs.gptr.dev/docs/gpt-researcher/gptr/pip-package) page.**
  116. ### 🔧 MCP Client
  117. GPT Researcher supports MCP integration to connect with specialized data sources like GitHub repositories, databases, and custom APIs. This enables research from data sources alongside web search.
  118. ```bash
  119. export RETRIEVER=tavily,mcp # Enable hybrid web + MCP research
  120. ```
  121. ```python
  122. from gpt_researcher import GPTResearcher
  123. import asyncio
  124. import os
  125. async def mcp_research_example():
  126. # Enable MCP with web search
  127. os.environ["RETRIEVER"] = "tavily,mcp"
  128. researcher = GPTResearcher(
  129. query="What are the top open source web research agents?",
  130. mcp_configs=[
  131. {
  132. "name": "github",
  133. "command": "npx",
  134. "args": ["-y", "@modelcontextprotocol/server-github"],
  135. "env": {"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")}
  136. }
  137. ]
  138. )
  139. research_result = await researcher.conduct_research()
  140. report = await researcher.write_report()
  141. return report
  142. ```
  143. > For comprehensive MCP documentation and advanced examples, visit the [MCP Integration Guide](https://docs.gptr.dev/docs/gpt-researcher/retrievers/mcp-configs).
  144. ## 🍌 Inline Image Generation
  145. GPT Researcher can automatically generate and embed AI-created illustrations in your research reports using Google's Gemini models (Nano Banana).
  146. ```bash
  147. # Enable in your .env file
  148. IMAGE_GENERATION_ENABLED=true
  149. GOOGLE_API_KEY=your_google_api_key
  150. IMAGE_GENERATION_MODEL=models/gemini-2.5-flash-image
  151. ```
  152. When enabled, the system will:
  153. 1. Analyze your research context to identify visualization opportunities
  154. 2. Pre-generate 2-3 relevant images during the research phase
  155. 3. Embed them inline as the report is written
  156. Images are generated with dark-mode styling that matches the GPT Researcher UI, featuring professional infographic aesthetics with teal accents.
  157. [Learn more about Image Generation](https://docs.gptr.dev/docs/gpt-researcher/gptr/image_generation) in our documentation.
  158. ## ✨ Deep Research
  159. GPT Researcher now includes Deep Research - an advanced recursive research workflow that explores topics with agentic depth and breadth. This feature employs a tree-like exploration pattern, diving deeper into subtopics while maintaining a comprehensive view of the research subject.
  160. - 🌳 Tree-like exploration with configurable depth and breadth
  161. - ⚡️ Concurrent processing for faster results
  162. - 🤝 Smart context management across research branches
  163. - ⏱️ Takes ~5 minutes per deep research
  164. - 💰 Costs ~$0.4 per research (using `o3-mini` on "high" reasoning effort)
  165. [Learn more about Deep Research](https://docs.gptr.dev/docs/gpt-researcher/gptr/deep_research) in our documentation.
  166. ## 🎯 Smart Context Filtering with Jev
  167. Every research run scrapes dozens of pages, and only some of each page helps answer the question. Before anything reaches the LLM, GPT Researcher decides which passages to keep. By default it uses **[Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev)** by TypeSafe, a model that scores how useful each passage is for the question, rather than how similar its words or embedding are.
  168. **Jev's context is 59% more relevant than embeddings, at the same cost** (73% of kept passages relevant vs 46%). We benchmarked every option on 28 research tasks, replaying the same scraped sources so that only the filter changed:
  169. | Context filter | Relevant passages kept | Head-to-head vs embeddings | Filter time | Cost per report | Needs |
  170. |---|---|---|---|---|---|
  171. | **Jev** (default) | **73%** | **15 wins · 10 ties · 3 losses** | 1.7s | $0.115 | `TYPESAFE_API_KEY` |
  172. | Keyword (fallback) | 51% | 14 wins · 8 ties · 6 losses | 0.02s | $0.116 | nothing |
  173. | Embeddings | 46% | — | 1.0s | $0.117 | an embedding provider |
  174. | No filter | — | 13 wins · 11 ties · 4 losses | — | $0.192 | nothing |
  175. Writing the report takes ~45s whichever filter you use, so a run's total time moves only by the filter step. Passing every page unfiltered writes the broadest reports on open-ended questions, but costs 65% more.
  176. **Nothing is required.** With a `TYPESAFE_API_KEY`, Jev is used. Without one, or if a Jev call fails, GPT Researcher falls back to keyword (BM25) ranking, which runs locally with no API key, model or embeddings. Embeddings remain available as an option.
  177. ```bash
  178. export TYPESAFE_API_KEY=... # use Jev (the default when a key is set)
  179. export CONTEXT_FILTER=auto # auto | jev | keyword | embeddings | none
  180. ```
  181. See the [Context Filter docs](https://docs.gptr.dev/docs/gpt-researcher/gptr/context-filter) and the [full benchmark](evals/context_filter) for method, caveats and how to reproduce it.
  182. ## Run with Docker
  183. > **Step 1** - [Install Docker](https://docs.gptr.dev/docs/gpt-researcher/getting-started/getting-started-with-docker)
  184. > **Step 2** - Clone the '.env.example' file, add your API Keys to the cloned file and save the file as '.env'
  185. > **Step 3** - Within the docker-compose file comment out services that you don't want to run with Docker.
  186. ```bash
  187. docker-compose up --build
  188. ```
  189. If that doesn't work, try running it without the dash:
  190. ```bash
  191. docker compose up --build
  192. ```
  193. > **Step 4** - By default, if you haven't uncommented anything in your docker-compose file, this flow will start 2 processes:
  194. - the Python server running on localhost:8000<br>
  195. - the React app running on localhost:3000<br>
  196. Visit localhost:3000 on any browser and enjoy researching!
  197. ## 📄 Research on Local Documents
  198. You can instruct the GPT Researcher to run research tasks based on your local documents. Currently supported file formats are: PDF, plain text, CSV, Excel, Markdown, PowerPoint, and Word documents.
  199. Step 1: Add the env variable `DOC_PATH` pointing to the folder where your documents are located.
  200. ```bash
  201. export DOC_PATH="./my-docs"
  202. ```
  203. Step 2:
  204. - If you're running the frontend app on localhost:8000, simply select "My Documents" from the "Report Source" Dropdown Options.
  205. - If you're running GPT Researcher with the [PIP package](https://docs.tavily.com/guides/gpt-researcher/gpt-researcher#pip-package), pass the `report_source` argument as "local" when you instantiate the `GPTResearcher` class [code sample here](https://docs.gptr.dev/docs/gpt-researcher/context/tailored-research).
  206. ## 🤖 MCP Server
  207. We've moved our MCP server to a dedicated repository: [gptr-mcp](https://github.com/assafelovic/gptr-mcp).
  208. The GPT Researcher MCP Server enables AI applications like Claude to conduct deep research. While LLM apps can access web search tools with MCP, GPT Researcher MCP delivers deeper, more reliable research results.
  209. Features:
  210. - Deep research capabilities for AI assistants
  211. - Higher quality information with optimized context usage
  212. - Comprehensive results with better reasoning for LLMs
  213. - Claude Desktop integration
  214. For detailed installation and usage instructions, please visit the [official repository](https://github.com/assafelovic/gptr-mcp).
  215. ## 👪 Multi-Agent Assistant
  216. As AI evolves from prompt engineering and RAG to multi-agent systems, we're excited to introduce multi-agent assistants built with [LangGraph](https://python.langchain.com/v0.1/docs/langgraph/) and [AG2](https://github.com/ag2ai/ag2).
  217. By using multi-agent frameworks, the research process can be significantly improved in depth and quality by leveraging multiple agents with specialized skills. This project showcases how a team of AI agents can work together to conduct research on a given topic, from planning to publication.
  218. An average run generates a 5-6 page research report in multiple formats such as PDF, Docx and Markdown.
  219. Check it out [here](https://github.com/assafelovic/gpt-researcher/tree/master/multi_agents) or head over to our documentation for [LangGraph](https://docs.gptr.dev/docs/gpt-researcher/multi_agents/langgraph) and [AG2](https://docs.gptr.dev/docs/gpt-researcher/multi_agents/ag2) for more information.
  220. ## 🔍 Observability
  221. GPT Researcher supports **LangSmith** for enhanced tracing and observability, making it easier to debug and optimize complex multi-agent workflows.
  222. To enable tracing:
  223. 1. Set the following environment variables:
  224. ```bash
  225. export LANGCHAIN_TRACING_V2=true
  226. export LANGCHAIN_API_KEY=your_api_key
  227. export LANGCHAIN_PROJECT="gpt-researcher"
  228. ```
  229. 2. Run your research tasks as usual. All LangGraph-based agent interactions will be automatically traced and visualized in your LangSmith dashboard.
  230. ## 🖥️ Frontend Applications
  231. GPT-Researcher now features an enhanced frontend to improve the user experience and streamline the research process. The frontend offers:
  232. - An intuitive interface for inputting research queries
  233. - Real-time progress tracking of research tasks
  234. - Interactive display of research findings
  235. - Customizable settings for tailored research experiences
  236. Two deployment options are available:
  237. 1. A lightweight static frontend served by FastAPI
  238. 2. A feature-rich NextJS application for advanced functionality
  239. For detailed setup instructions and more information about the frontend features, please visit our [documentation page](https://docs.gptr.dev/docs/gpt-researcher/frontend/introduction).
  240. ## 🚀 Contributing
  241. We highly welcome contributions! Please check out [contributing](https://github.com/assafelovic/gpt-researcher/blob/master/CONTRIBUTING.md) if you're interested.
  242. Please check out our [roadmap](https://trello.com/b/3O7KBePw/gpt-researcher-roadmap) page and reach out to us via our [Discord community](https://discord.gg/QgZXvJAccX) if you're interested in joining our mission.
  243. <a href="https://github.com/assafelovic/gpt-researcher/graphs/contributors">
  244. <img src="https://contrib.rocks/image?repo=assafelovic/gpt-researcher&max=1000" />
  245. </a>
  246. ## ✉️ Support / Contact us
  247. - [Community Discord](https://discord.gg/spBgZmm3Xe)
  248. - Author Email: assaf.elovic@gmail.com
  249. ## 🛡 Disclaimer
  250. This project, GPT Researcher, is an experimental application and is provided "as-is" without any warranty, express or implied. We are sharing codes for academic purposes under the Apache 2 license. Nothing herein is academic advice, and NOT a recommendation to use in academic or research papers.
  251. Our view on unbiased research claims:
  252. 1. The main goal of GPT Researcher is to reduce incorrect and biased facts. How? We assume that the more sites we scrape the less chances of incorrect data. By scraping multiple sites per research, and choosing the most frequent information, the chances that they are all wrong is extremely low.
  253. 2. We do not aim to eliminate biases; we aim to reduce it as much as possible. **We are here as a community to figure out the most effective human/llm interactions.**
  254. 3. In research, people also tend towards biases as most have already opinions on the topics they research about. This tool scrapes many opinions and will evenly explain diverse views that a biased person would never have read.
  255. ---
  256. <p align="center">
  257. <a href="https://star-history.com/#assafelovic/gpt-researcher">
  258. <picture>
  259. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=assafelovic/gpt-researcher&type=Date&theme=dark" />
  260. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=assafelovic/gpt-researcher&type=Date" />
  261. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=assafelovic/gpt-researcher&type=Date" />
  262. </picture>
  263. </a>
  264. </p>
  265. <p align="right">
  266. <a href="#top">⬆️ Back to Top</a>
  267. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

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