GPT Researcher: An Open Source Deep Research Agent That Plans, Executes, and Cites

What GPT Researcher Actually Solves

GPT Researcher addresses a specific failure mode: manual research that takes weeks, and LLMs that hallucinate because they are trained on outdated data. The README lists token limitations and limited web sources as core problems. The tool is for engineers, analysts, and knowledge workers who need a long-form, cited report on a current topic without hand-curating every source. It is not a chatbot. It is an agent that decomposes a query into sub-questions, fetches information, and aggregates findings into a report that can exceed 2,000 words. The target user is someone who values reproducibility and source tracking over a quick chat answer. The project positions itself as the first open deep research agent for both web and local research, which is a specific claim you can verify by running it.

Planner and Execution Agents: The Core Mechanism

The architecture is built on two agent types. A planner agent generates research questions from the user's query. Execution agents then gather information for each question. A crawler agent handles the actual fetching, and a publisher aggregates the summaries into a final report. The README describes five steps: create a task-specific agent, generate questions, use a crawler, summarize and source-track each resource, then filter and aggregate. This is a classic plan-and-execute pattern. The key design choice is parallelism. The README claims increased speed through parallelized agent work, which means multiple execution agents can run concurrently for different questions. This is a real architectural difference from a single sequential LLM call. The trade-off is complexity: you have multiple moving parts, each of which can fail independently.

Getting It Running: Commands and Configuration

The README gives a clear path. You need Python 3.12 or later. Clone the repository, then set two environment variables: OPENAI_API_KEY and TAVILY_API_KEY. You can also set OPENAI_BASE_URL for custom OpenAI-compatible APIs, for example for local models or other providers. Optional LangChain tracing variables are listed but commented out. Then install dependencies and start the server with pip install -r requirements.txt and python -m uvicorn main:app --reload. The web UI is at http://localhost:8000. There is also a pip package. You can install gpt-researcher and use the GPTResearcher class in Python. The example shows a query about Nvidia stock, then await researcher.conduct_research() and await researcher.write_report(). For MCP integration, you set RETRIEVER=tavily,mcp and pass mcp_configs with a command and args, like npx with the GitHub server. The configuration is environment-variable driven, which is simple but means you need to manage a .env file carefully.

Retrievers and the MCP Client: Extending Data Sources

GPT Researcher supports multiple retrievers, and the README specifically highlights MCP integration. The RETRIEVER environment variable accepts a comma-separated list. The example shows tavily,mcp to combine web search with MCP-based sources. The MCP client lets you connect to GitHub repositories, databases, and custom APIs through the Model Context Protocol. This is a significant extension point. Instead of only searching the web, you can pull data from private or specialized sources. The README gives a concrete example: a GitHub MCP server that uses npx to run @modelcontextprotocol/server-github with a GITHUB_TOKEN. This means you can research code repositories directly. The limitation is that MCP servers are external processes, so you need to manage their lifecycle and dependencies.

Inline Image Generation and Report Formats

A notable feature is AI-generated inline images. The README mentions Google Gemini models, specifically the Nano Banana model, for creating illustrations within reports. You enable this via the IMAGE_GENERATION_ENABLED environment variable, which docker-compose.yml defaults to false. This is an optional feature that adds visual context but also adds another API dependency. The tool also supports smart image scraping and filtering for reports, which means it can pull relevant images from the web. Reports can be exported to PDF, Word, and other formats, which is important for integration into workflows. The frontend comes in two versions: a lightweight HTML/CSS/JS version and a production-ready NextJS + Tailwind version. This is a practical choice. You can run the lightweight version for a quick test, then switch to the full frontend for deployment.

Real Limitations and Failure Modes

The most obvious limitation is external dependency. GPT Researcher requires API keys for both an LLM provider and a search retriever, typically OpenAI and Tavily. If either service is down or rate-limited, the research fails. Another limitation is determinism. The agent generates questions and gathers sources based on LLM output, which is probabilistic. Two runs on the same query may produce different reports. The token limitation that the README cites as a problem is only partially solved by parallelization. Long reports still need to be aggregated, and the publisher agent has a context window limit. Finally, the tool is wrong for simple queries. If you need a one-paragraph answer, spinning up a planner, execution agents, and a publisher is overkill. The README's own example, 'why is Nvidia stock going up?', is a research question, not a chat prompt.

Alternatives and How They Differ

The closest alternative is a manual RAG pipeline built with LangChain or LlamaIndex. The difference is in control. With a custom RAG pipeline, you decide the chunk size, the embedding model, and the retrieval strategy. GPT Researcher abstracts those decisions away. It gives you a higher-level API but less control. Another alternative is using a single LLM with a web search tool, like a ChatGPT plugin. That approach is simpler but produces shorter, less cited outputs. GPT Researcher's advantage is the multi-agent structure and the aggregation step, which is designed for long reports. However, if you need to fine-tune the retrieval logic or use a specific vector store, a custom pipeline gives you more flexibility. The choice is between a turnkey agent and a component library.

Maintenance, License, and Upgrade Cost

The project is under active development. The last push was October 2026, and the recent releases are v3.7.0, v3.6.1, and v3.6.0. This means you can expect frequent changes. The repository metadata lists the license as Apache-2.0, while pyproject.toml and setup.py declare MIT; both are permissive, but read the LICENSE file for your specific use case. The upgrade cost is moderate. Since the configuration is environment-variable based, upgrading usually means pulling new code and reinstalling dependencies. The dependency on external APIs means you also need to track changes to those APIs. For example, if Tavily changes its API, you may need to update your retriever configuration. The project has a documentation site and a Discord. For production use, budget time for testing each new release.

Editorial conclusion

Adopt GPT Researcher if you need a self-hosted research pipeline that can pull from multiple web sources and local documents, and if you are comfortable managing API keys and a Python environment. Do not use it if you require deterministic, fully verifiable output, because the agent depends on external search and LLM providers that can change behavior. Before adopting, verify that your chosen retriever and LLM provider are supported, and test a small query end to end to confirm the report quality and citation format meet your needs.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes