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. - 🧠 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 reasoningeffort defaults based
Add this skill
npx mdskills install ConechoAI/openai-websearch-mcpWell-documented MCP server with rich OpenAI integration but permissions overstated for API tool
1# OpenAI WebSearch MCP Server 🔍23[](https://badge.fury.io/py/openai-websearch-mcp)4[](https://www.python.org/downloads/)5[](https://modelcontextprotocol.io/)6[](https://opensource.org/licenses/MIT)78An 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.910## ✨ Features1112- **🧠 Reasoning Model Support**: Full compatibility with OpenAI's latest reasoning models (gpt-5, gpt-5-mini, gpt-5-nano, o3, o4-mini)13- **⚡ Smart Effort Control**: Intelligent `reasoning_effort` defaults based on use case14- **🔄 Multi-Mode Search**: Fast iterations with gpt-5-mini or deep research with gpt-515- **🌍 Localized Results**: Support for location-based search customization16- **📝 Rich Descriptions**: Complete parameter documentation for easy integration17- **🔧 Flexible Configuration**: Environment variable support for easy deployment1819## 🚀 Quick Start2021### One-Click Installation for Claude Desktop2223```bash24OPENAI_API_KEY=sk-xxxx uvx --with openai-websearch-mcp openai-websearch-mcp-install25```2627Replace `sk-xxxx` with your OpenAI API key from the [OpenAI Platform](https://platform.openai.com/).2829## ⚙️ Configuration3031### Claude Desktop3233Add to your `claude_desktop_config.json`:3435```json36{37 "mcpServers": {38 "openai-websearch-mcp": {39 "command": "uvx",40 "args": ["openai-websearch-mcp"],41 "env": {42 "OPENAI_API_KEY": "your-api-key-here",43 "OPENAI_DEFAULT_MODEL": "gpt-5-mini"44 }45 }46 }47}48```4950### Cursor5152Add to your MCP settings in Cursor:53541. Open Cursor Settings (`Cmd/Ctrl + ,`)552. Search for "MCP" or go to Extensions → MCP563. Add server configuration:5758```json59{60 "mcpServers": {61 "openai-websearch-mcp": {62 "command": "uvx",63 "args": ["openai-websearch-mcp"],64 "env": {65 "OPENAI_API_KEY": "your-api-key-here",66 "OPENAI_DEFAULT_MODEL": "gpt-5-mini"67 }68 }69 }70}71```7273### Claude Code7475Claude Code automatically detects MCP servers configured for Claude Desktop. Use the same configuration as above for Claude Desktop.7677### Local Development7879For local testing, use the absolute path to your virtual environment:8081```json82{83 "mcpServers": {84 "openai-websearch-mcp": {85 "command": "/path/to/your/project/.venv/bin/python",86 "args": ["-m", "openai_websearch_mcp"],87 "env": {88 "OPENAI_API_KEY": "your-api-key-here",89 "OPENAI_DEFAULT_MODEL": "gpt-5-mini",90 "PYTHONPATH": "/path/to/your/project/src"91 }92 }93 }94}95```9697## 🛠️ Available Tools9899### `openai_web_search`100101Intelligent web search with reasoning model support.102103#### Parameters104105| Parameter | Type | Description | Default |106|-----------|------|-------------|---------|107| `input` | `string` | The search query or question to search for | *Required* |108| `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` |109| `reasoning_effort` | `string` | Reasoning effort level: low, medium, high, minimal | Smart default |110| `type` | `string` | Web search API version | `web_search_preview` |111| `search_context_size` | `string` | Context amount: low, medium, high | `medium` |112| `user_location` | `object` | Optional location for localized results | `null` |113114## 💬 Usage Examples115116Once configured, simply ask your AI assistant to search for information using natural language:117118### Quick Search119> "Search for the latest developments in AI reasoning models using openai_web_search"120121### Deep Research122> "Use openai_web_search with gpt-5 and high reasoning effort to provide a comprehensive analysis of quantum computing breakthroughs"123124### Localized Search125> "Search for local tech meetups in San Francisco this week using openai_web_search"126127The AI assistant will automatically use the `openai_web_search` tool with appropriate parameters based on your request.128129## 🤖 Model Selection Guide130131### Quick Multi-Round Searches 🚀132- **Recommended**: `gpt-5-mini` with `reasoning_effort: "low"`133- **Use Case**: Fast iterations, real-time information, multiple quick queries134- **Benefits**: Lower latency, cost-effective for frequent searches135136### Deep Research 🔬137- **Recommended**: `gpt-5` with `reasoning_effort: "medium"` or `"high"`138- **Use Case**: Comprehensive analysis, complex topics, detailed investigation139- **Benefits**: Multi-round reasoned results, no need for agent iterations140141### Model Comparison142143| Model | Reasoning | Default Effort | Best For |144|-------|-----------|----------------|----------|145| `gpt-4o` | ❌ | N/A | Standard search |146| `gpt-4o-mini` | ❌ | N/A | Basic queries |147| `gpt-5-mini` | ✅ | `low` | Fast iterations |148| `gpt-5` | ✅ | `medium` | Deep research |149| `gpt-5-nano` | ✅ | `medium` | Balanced approach |150| `o3` | ✅ | `medium` | Advanced reasoning |151| `o4-mini` | ✅ | `medium` | Efficient reasoning |152153## 📦 Installation154155### Using uvx (Recommended)156157```bash158# Install and run directly159uvx openai-websearch-mcp160161# Or install globally162uvx install openai-websearch-mcp163```164165### Using pip166167```bash168# Install from PyPI169pip install openai-websearch-mcp170171# Run the server172python -m openai_websearch_mcp173```174175### From Source176177```bash178# Clone the repository179git clone https://github.com/yourusername/openai-websearch-mcp.git180cd openai-websearch-mcp181182# Install dependencies183uv sync184185# Run in development mode186uv run python -m openai_websearch_mcp187```188189## 👩💻 Development190191### Setup Development Environment192193```bash194# Clone and setup195git clone https://github.com/yourusername/openai-websearch-mcp.git196cd openai-websearch-mcp197198# Create virtual environment and install dependencies199uv sync200201# Run tests202uv run python -m pytest203204# Install in development mode205uv pip install -e .206```207208### Environment Variables209210| Variable | Description | Default |211|----------|-------------|---------|212| `OPENAI_API_KEY` | Your OpenAI API key | *Required* |213| `OPENAI_DEFAULT_MODEL` | Default model to use | `gpt-5-mini` |214215## 🐛 Debugging216217### Using MCP Inspector218219```bash220# For uvx installations221npx @modelcontextprotocol/inspector uvx openai-websearch-mcp222223# For pip installations224npx @modelcontextprotocol/inspector python -m openai_websearch_mcp225```226227### Common Issues228229**Issue**: "Unsupported parameter: 'reasoning.effort'"230**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.231232**Issue**: "No module named 'openai_websearch_mcp'"233**Solution**: Ensure you've installed the package correctly and your Python path includes the package location.234235## 📄 License236237This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.238239## 🙏 Acknowledgments240241- 🤖 Generated with [Claude Code](https://claude.ai/code)242- 🔥 Powered by [OpenAI's Web Search API](https://openai.com)243- 🛠️ Built on the [Model Context Protocol](https://modelcontextprotocol.io/)244245---246247**Co-Authored-By**: Claude <noreply@anthropic.com>
Full transparency — inspect the skill content before installing.