# OpenAI WebSearch MCP Server [](https://badge.fury.io/py/openai-websearch-mcp) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io/) [](https://opensource.org/licenses/MIT) An advanced MCP server that provides intelligent web search capabilities using OpenAI's reasoning models. Perfect for AI assistants that need up-to-date information with smart reasoning capabilities. ## Features - ** Reasoning Model Support**: Full compatibility with OpenAI's latest reasoning models (gpt-5, gpt-5-mini, gpt-5-nano, o3, o4-mini) - ** Smart Effort Control**: Intelligent \`reasoning_effort\` defaults based on use case - ** Multi-Mode Search**: Fast iterations with gpt-5-mini or deep research with gpt-5 - ** Localized Results**: Support for location-based search customization - ** Rich Descriptions**: Complete parameter documentation for easy integration - ** Flexible Configuration**: Environment variable support for easy deployment ## Quick Start ### One-Click Installation for Claude Desktop \`\`\`bash OPENAI_API_KEY=sk-xxxx uvx --with openai-websearch-mcp openai-websearch-mcp-install \`\`\` Replace \`sk-xxxx\` with your OpenAI API key from the [OpenAI Platform](https://platform.openai.com/). ## ️ Configuration ### Claude Desktop Add to your \`claude_desktop_config.json\`: \`\`\`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 Add to your MCP settings in Cursor: 1. Open Cursor Settings (\`Cmd/Ctrl + ,\`) 2. Search for "MCP" or go to Extensions → MCP 3. Add server configuration: \`\`\`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" \} \} \} \} \`\`\` ### Claude Code Claude Code automatically detects MCP servers configured for Claude Desktop. Use the same configuration as above for Claude Desktop. ### Local Development For local testing, use the absolute path to your virtual environment: \`\`\`json \{ "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" \} \} \} \} \`\`\` ## ️ Available Tools ### \`openai_web_search\` Intelligent web search with reasoning model support. #### Parameters | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | \`input\` | \`string\` | The search query or question to search for | *Required* | | \`model\` | \`string\` | AI model to use. Supports gpt-4o, gpt-4o-mini, gpt-5, gpt-5-mini, gpt-5-nano, o3, o4-mini | \`gpt-5-mini\` | | \`reasoning_effort\` | \`string\` | Reasoning effort level: low, medium, high, minimal | Smart default | | \`type\` | \`string\` | Web search API version | \`web_search_preview\` | | \`search_context_size\` | \`string\` | Context amount: low, medium, high | \`medium\` | | \`user_location\` | \`object\` | Optional location for localized results | \`null\` | ## Usage Examples Once configured, simply ask your AI assistant to search for information using natural language: ### Quick Search > "Search for the latest developments in AI reasoning models using openai_web_search" ### Deep Research > "Use openai_web_search with gpt-5 and high reasoning effort to provide a comprehensive analysis of quantum computing breakthroughs" ### Localized Search > "Search for local tech meetups in San Francisco this week using openai_web_search" The AI assistant will automatically use the \`openai_web_search\` tool with appropriate parameters based on your request. ## Model Selection Guide ### Quick Multi-Round Searches - **Recommended**: \`gpt-5-mini\` with \`reasoning_effort: "low"\` - **Use Case**: Fast iterations, real-time information, multiple quick queries - **Benefits**: Lower latency, cost-effective for frequent searches ### Deep Research - **Recommended**: \`gpt-5\` with \`reasoning_effort: "medium"\` or \`"high"\` - **Use Case**: Comprehensive analysis, complex topics, detailed investigation - **Benefits**: Multi-round reasoned results, no need for agent iterations ### Model Comparison | Model | Reasoning | Default Effort | Best For | |-------|-----------|----------------|----------| | \`gpt-4o\` | | N/A | Standard search | | \`gpt-4o-mini\` | | N/A | Basic queries | | \`gpt-5-mini\` | | \`low\` | Fast iterations | | \`gpt-5\` | | \`medium\` | Deep research | | \`gpt-5-nano\` | | \`medium\` | Balanced approach | | \`o3\` | | \`medium\` | Advanced reasoning | | \`o4-mini\` | | \`medium\` | Efficient reasoning | ## Installation ### Using uvx (Recommended) \`\`\`bash # Install and run directly uvx openai-websearch-mcp # Or install globally uvx install openai-websearch-mcp \`\`\` ### Using pip \`\`\`bash # Install from PyPI pip install openai-websearch-mcp # Run the server python -m openai_websearch_mcp \`\`\` ### From Source \`\`\`bash # 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 \`\`\` ## ‍ Development ### Setup Development Environment \`\`\`bash # 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 . \`\`\` ### Environment Variables | Variable | Description | Default | |----------|-------------|---------| | \`OPENAI_API_KEY\` | Your OpenAI API key | *Required* | | \`OPENAI_DEFAULT_MODEL\` | Default model to use | \`gpt-5-mini\` | ## Debugging ### Using MCP Inspector \`\`\`bash # For uvx installations npx @modelcontextprotocol/inspector uvx openai-websearch-mcp # For pip installations npx @modelcontextprotocol/inspector python -m openai_websearch_mcp \`\`\` ### Common Issues **Issue**: "Unsupported parameter: 'reasoning.effort'" **Solution**: This occurs when using non-reasoning models (gpt-4o, gpt-4o-mini) with reasoning_effort parameter. The server automatically handles this by only applying reasoning parameters to compatible models. **Issue**: "No module named 'openai_websearch_mcp'" **Solution**: Ensure you've installed the package correctly and your Python path includes the package location. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Acknowledgments - Generated with [Claude Code](https://claude.ai/code) - Powered by [OpenAI's Web Search API](https://openai.com) - ️ Built on the [Model Context Protocol](https://modelcontextprotocol.io/) --- **Co-Authored-By**: Claude