Files

Krishna Kumar 9a6ac3fd2f Add OpenAI Deep Research MCP server

- FastMCP server with deep_research and deep_research_info tools
- OpenAI Responses API integration with background polling
- Configurable model via DEEP_RESEARCH_MODEL env var
- Default: o4-mini-deep-research (faster/cheaper)
- Optional FastAPI backend for standalone use
- Tested successfully: 80s query, 20 web searches, 4 citations

2025-12-30 16:00:37 -06:00

3.1 KiB

Raw Permalink Blame History

MCP Deep Research

MCP Server for OpenAI Deep Research API - comprehensive web research with citations.

Overview

This MCP server provides access to OpenAI's Deep Research models, which can:

Perform extensive web searches
Analyze data with code execution
Synthesize findings into structured reports
Provide citations for all sources

Installation

cd mcp-deep-research
uv sync

Configuration

Environment Variables

Variable	Required	Default	Description
`OPENAI_API_KEY`	Yes	-	Your OpenAI API key
`DEEP_RESEARCH_MODEL`	No	`o4-mini-deep-research-2025-06-26`	Research model to use
`DEEP_RESEARCH_POLL_INTERVAL`	No	`5.0`	Seconds between status polls

Available Models

o4-mini-deep-research-2025-06-26 - Faster, cheaper (DEFAULT)
o3-deep-research-2025-06-26 - More thorough, ~$1+ per query

Usage

As MCP Server (stdio)

OPENAI_API_KEY=your-key uv run python -m mcp_server.server

Standalone FastAPI (optional)

OPENAI_API_KEY=your-key uv run python -m backend.main

Runs on http://localhost:8002 by default.

MCP Tools

`deep_research`

Performs comprehensive web research on a query.

Parameters:

query (required): The research question or topic
system_prompt (optional): Instructions to guide research focus
include_code_analysis (optional, default: true): Allow code execution for data analysis
max_wait_minutes (optional, default: 15): Maximum time to wait

Returns:

{
  "status": "completed",
  "model": "o4-mini-deep-research-2025-06-26",
  "report_text": "# Research Report\n\n...",
  "citations": [
    {"title": "Source Title", "url": "https://..."}
  ],
  "web_searches": 12,
  "code_executions": 2,
  "elapsed_time": 180.5
}

`deep_research_info`

Returns configuration information about the deep research setup.

Integration with CouncilApp

The server is configured in councilapp.backend/packages/server/src/server/session.ts:

"deep-research": {
  command: "/bin/bash",
  args: ["-c", `cd ${MCP_DEEP_RESEARCH_PATH} && uv run python -m mcp_server.server`],
  env: {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
    DEEP_RESEARCH_MODEL: process.env.DEEP_RESEARCH_MODEL,
  },
}

Docker Configuration

Set these in your Docker environment or docker-compose.yml:

environment:
  - OPENAI_API_KEY=sk-...
  - DEEP_RESEARCH_MODEL=o4-mini-deep-research-2025-06-26  # or o3-deep-research-2025-06-26

Pricing

Deep research costs vary based on:

Number of web searches performed
Code interpreter usage
Token consumption

Approximate costs:

o4-mini: Lower cost, faster responses
o3: ~$1+ per complex query with many web searches

Test Results (2024-12-30)

Successfully tested with query: "What is the current population of Tokyo in 2024?"

Status: completed
Model: o4-mini-deep-research-2025-06-26
Elapsed time: 80.5s
Web searches: 20
Citations: 4

Report excerpt:
# Tokyo Population (2024)
As of late 2024, the official population of Tokyo Metropolis is about 14.2 million people.

License

MIT

3.1 KiB Raw Permalink Blame History