The two shapes matter: complete-research is convenient but opaque and prone to timing out on a big topic, while initialize-research plus repeated steps lets you watch the depth counter, read the findings resource between rounds, and stop when you have enough. Depth is also the cost dial — each round means more Firecrawl scrapes and more OpenAI tokens on your own keys — and the repository's own advice for token-limit errors is to lower it and narrow the query.
A TypeScript server that runs a multi-round research loop: it identifies gaps, searches and scrapes the web through Firecrawl, analyses with OpenAI, and writes the findings up as a report.
- initialize-research — start a session from a query and a depth, and get a session ID back
- execute-research-step — advance one round, with each round generating queries aimed at the gaps left by the last
- generate-report — the finished write-up, with an optional timeout for long topics
- complete-research — the whole loop in one call when you do not want to drive the steps yourself
- Session state and collected findings readable as resources at research://state/{sessionId} and research://findings/{sessionId}
- A report laid out as executive summary, introduction, methodology, analysis, comparison, discussion, limitations, conclusion and bibliography
- Sources cited with numbered references and URLs
- Partial reports when a round fails, rather than losing the session
Two paid keys of your own — OPENAI_API_KEY and FIRECRAWL_API_KEY — and Node.js 18 or higher. Both run up usage on your accounts, and depth is the dial that decides how much.
One command plus a key — npx -y deep-research-mcp, then supply credentials