OpenAI WebSearch MCP Server

OpenAI WebSearch MCP 服务 🔍

一款先进的 MCP 服务，使用 OpenAI 的推理模型提供智能网页搜索功能。非常适合需要通过智能推理获取最新信息的 AI 助手。

✨ 功能

• 🧠 推理模型支持：全面兼容 OpenAI 最新的推理模型（gpt-5、gpt-5-mini、gpt-5-nano、o3、o4-mini）
• ⚡ 智能工作量控制：根据使用场景智能设置 reasoning_effort 默认值
• 🔄 多模式搜索：使用 gpt-5-mini 快速迭代，或使用 gpt-5 深入研究
• 🌍 本地化结果：支持基于位置定制搜索
• 📝 丰富的描述：提供完整的参数文档，便于集成
• 🔧 灵活的配置：支持环境变量，便于部署

🚀 快速开始

Claude Desktop 一键安装

OPENAI_API_KEY=sk-xxxx uvx --with openai-websearch-mcp openai-websearch-mcp-install

将 sk-xxxx 替换为你从 OpenAI Platform 获取的 OpenAI API 密钥。

⚙️ 配置

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "openai-websearch-mcp": {
      "command": "uvx",
      "args": ["openai-websearch-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "OPENAI_DEFAULT_MODEL": "gpt-5-mini"
      }
    }
  }
}

Cursor

在 Cursor 的 MCP 设置中添加：

1. 打开 Cursor 设置（Cmd/Ctrl + ,）
2. 搜索“MCP”或前往“扩展 → MCP”
3. 添加服务配置：

{
  "mcpServers": {
    "openai-websearch-mcp": {
      "command": "uvx",
      "args": ["openai-websearch-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "OPENAI_DEFAULT_MODEL": "gpt-5-mini"
      }
    }
  }
}

Claude Code

Claude Code 会自动检测为 Claude Desktop 配置的 MCP 服务。使用上述 Claude Desktop 的相同配置即可。

本地开发

进行本地测试时，请使用虚拟环境的绝对路径：

{
  "mcpServers": {
    "openai-websearch-mcp": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["-m", "openai_websearch_mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "OPENAI_DEFAULT_MODEL": "gpt-5-mini",
        "PYTHONPATH": "/path/to/your/project/src"
      }
    }
  }
}

🛠️ 可用工具

openai_web_search

支持推理模型的智能网页搜索。

参数

参数	类型	描述	默认值
input	string	要搜索的查询或问题	必填
model	string	要使用的 AI 模型。支持 gpt-4o、gpt-4o-mini、gpt-5、gpt-5-mini、gpt-5-nano、o3、o4-mini	gpt-5-mini
reasoning_effort	string	推理工作量级别：low、medium、high、minimal	智能默认值
type	string	网页搜索 API 版本	web_search_preview
search_context_size	string	上下文量：low、medium、high	medium
user_location	object	可选的位置，用于获取本地化结果	null

💬 使用示例

配置完成后，只需用自然语言让 AI 助手搜索信息：

快速搜索

“使用 openai_web_search 搜索 AI 推理模型的最新进展”

深入研究

“使用 gpt-5 和 high 推理工作量，通过 openai_web_search 全面分析量子计算的突破”

本地化搜索

“使用 openai_web_search 搜索本周旧金山当地的科技聚会”

AI 助手会根据你的请求，自动使用带有适当参数的 openai_web_search 工具。

🤖 模型选择指南

快速多轮搜索 🚀

• 推荐：使用 gpt-5-mini，并将 reasoning_effort 设为 "low"
• 使用场景：快速迭代、实时信息、多个快速查询
• 优势：延迟更低，适合频繁搜索，成本效益高

深入研究 🔬

• 推荐：使用 gpt-5，并将 reasoning_effort 设为 "medium" 或 "high"
• 使用场景：全面分析、复杂主题、详细调查
• 优势：提供多轮推理结果，无需 Agent 迭代

模型对比

模型	推理能力	默认推理力度	适用场景
gpt-4o	❌	不适用	常规搜索
gpt-4o-mini	❌	不适用	基础查询
gpt-5-mini	✅	low	快速迭代
gpt-5	✅	medium	深度研究
gpt-5-nano	✅	medium	均衡方案
o3	✅	medium	高级推理
o4-mini	✅	medium	高效推理

📦 安装

使用 uvx（推荐）

# Install and run directly
uvx openai-websearch-mcp

# Or install globally
uvx install openai-websearch-mcp

使用 pip

# Install from PyPI
pip install openai-websearch-mcp

# Run the server
python -m openai_websearch_mcp

从源代码安装

# Clone the repository
git clone https://github.com/yourusername/openai-websearch-mcp.git
cd openai-websearch-mcp

# Install dependencies
uv sync

# Run in development mode
uv run python -m openai_websearch_mcp

👩‍💻 开发

设置开发环境

# Clone and setup
git clone https://github.com/yourusername/openai-websearch-mcp.git
cd openai-websearch-mcp

# Create virtual environment and install dependencies
uv sync

# Run tests
uv run python -m pytest

# Install in development mode
uv pip install -e .

环境变量

变量	描述	默认值
OPENAI_API_KEY	你的 OpenAI API 密钥	必填
OPENAI_DEFAULT_MODEL	默认使用的模型	gpt-5-mini

🐛 调试

使用 MCP Inspector

# For uvx installations
npx @modelcontextprotocol/inspector uvx openai-websearch-mcp

# For pip installations
npx @modelcontextprotocol/inspector python -m openai_websearch_mcp

常见问题

问题：“Unsupported parameter: 'reasoning.effort'” 解决方案：使用非推理模型（gpt-4o、gpt-4o-mini）并设置 reasoning_effort 参数时会出现此问题。服务会自动处理，仅对兼容的模型应用推理参数。

问题：“No module named 'openai_websearch_mcp'” 解决方案：请确保已正确安装该软件包，并且 Python 路径包含该软件包的位置。

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🙏 致谢

• 🤖 使用 Claude Code 生成
• 🔥 由 OpenAI 的 Web Search API 提供支持
• 🛠️ 基于 Model Context Protocol 构建

---

共同创作者：Claude [email protected]