Skip to content
Back to search

openai-websearch-mcp

openai websearch tool as mcp server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/conechoai--openai-websearch-mcp/badge.svg)](/listings/conechoai--openai-websearch-mcp)

HTML

<a href="/listings/conechoai--openai-websearch-mcp"><img src="/api/listings/conechoai--openai-websearch-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

One-Click Installation for Claude Desktop

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/).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 247 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OpenAI WebSearch MCP Server 🔍
  2. [![PyPI version](https://badge.fury.io/py/openai-websearch-mcp.svg)](https://badge.fury.io/py/openai-websearch-mcp)
  3. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  4. [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. 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.
  7. ## ✨ Features
  8. - **🧠 Reasoning Model Support**: Full compatibility with OpenAI's latest reasoning models (gpt-5, gpt-5-mini, gpt-5-nano, o3, o4-mini)
  9. - **⚡ Smart Effort Control**: Intelligent `reasoning_effort` defaults based on use case
  10. - **🔄 Multi-Mode Search**: Fast iterations with gpt-5-mini or deep research with gpt-5
  11. - **🌍 Localized Results**: Support for location-based search customization
  12. - **📝 Rich Descriptions**: Complete parameter documentation for easy integration
  13. - **🔧 Flexible Configuration**: Environment variable support for easy deployment
  14. ## 🚀 Quick Start
  15. ### One-Click Installation for Claude Desktop
  16. ```bash
  17. OPENAI_API_KEY=sk-xxxx uvx --with openai-websearch-mcp openai-websearch-mcp-install
  18. ```
  19. Replace `sk-xxxx` with your OpenAI API key from the [OpenAI Platform](https://platform.openai.com/).
  20. ## ⚙️ Configuration
  21. ### Claude Desktop
  22. Add to your `claude_desktop_config.json`:
  23. ```json
  24. {
  25. "mcpServers": {
  26. "openai-websearch-mcp": {
  27. "command": "uvx",
  28. "args": ["openai-websearch-mcp"],
  29. "env": {
  30. "OPENAI_API_KEY": "your-api-key-here",
  31. "OPENAI_DEFAULT_MODEL": "gpt-5-mini"
  32. }
  33. }
  34. }
  35. }
  36. ```
  37. ### Cursor
  38. Add to your MCP settings in Cursor:
  39. 1. Open Cursor Settings (`Cmd/Ctrl + ,`)
  40. 2. Search for "MCP" or go to Extensions → MCP
  41. 3. Add server configuration:
  42. ```json
  43. {
  44. "mcpServers": {
  45. "openai-websearch-mcp": {
  46. "command": "uvx",
  47. "args": ["openai-websearch-mcp"],
  48. "env": {
  49. "OPENAI_API_KEY": "your-api-key-here",
  50. "OPENAI_DEFAULT_MODEL": "gpt-5-mini"
  51. }
  52. }
  53. }
  54. }
  55. ```
  56. ### Claude Code
  57. Claude Code automatically detects MCP servers configured for Claude Desktop. Use the same configuration as above for Claude Desktop.
  58. ### Local Development
  59. For local testing, use the absolute path to your virtual environment:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "openai-websearch-mcp": {
  64. "command": "/path/to/your/project/.venv/bin/python",
  65. "args": ["-m", "openai_websearch_mcp"],
  66. "env": {
  67. "OPENAI_API_KEY": "your-api-key-here",
  68. "OPENAI_DEFAULT_MODEL": "gpt-5-mini",
  69. "PYTHONPATH": "/path/to/your/project/src"
  70. }
  71. }
  72. }
  73. }
  74. ```
  75. ## 🛠️ Available Tools
  76. ### `openai_web_search`
  77. Intelligent web search with reasoning model support.
  78. #### Parameters
  79. | Parameter | Type | Description | Default |
  80. |-----------|------|-------------|---------|
  81. | `input` | `string` | The search query or question to search for | *Required* |
  82. | `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` |
  83. | `reasoning_effort` | `string` | Reasoning effort level: low, medium, high, minimal | Smart default |
  84. | `type` | `string` | Web search API version | `web_search_preview` |
  85. | `search_context_size` | `string` | Context amount: low, medium, high | `medium` |
  86. | `user_location` | `object` | Optional location for localized results | `null` |
  87. ## 💬 Usage Examples
  88. Once configured, simply ask your AI assistant to search for information using natural language:
  89. ### Quick Search
  90. > "Search for the latest developments in AI reasoning models using openai_web_search"
  91. ### Deep Research
  92. > "Use openai_web_search with gpt-5 and high reasoning effort to provide a comprehensive analysis of quantum computing breakthroughs"
  93. ### Localized Search
  94. > "Search for local tech meetups in San Francisco this week using openai_web_search"
  95. The AI assistant will automatically use the `openai_web_search` tool with appropriate parameters based on your request.
  96. ## 🤖 Model Selection Guide
  97. ### Quick Multi-Round Searches 🚀
  98. - **Recommended**: `gpt-5-mini` with `reasoning_effort: "low"`
  99. - **Use Case**: Fast iterations, real-time information, multiple quick queries
  100. - **Benefits**: Lower latency, cost-effective for frequent searches
  101. ### Deep Research 🔬
  102. - **Recommended**: `gpt-5` with `reasoning_effort: "medium"` or `"high"`
  103. - **Use Case**: Comprehensive analysis, complex topics, detailed investigation
  104. - **Benefits**: Multi-round reasoned results, no need for agent iterations
  105. ### Model Comparison
  106. | Model | Reasoning | Default Effort | Best For |
  107. |-------|-----------|----------------|----------|
  108. | `gpt-4o` | ❌ | N/A | Standard search |
  109. | `gpt-4o-mini` | ❌ | N/A | Basic queries |
  110. | `gpt-5-mini` | ✅ | `low` | Fast iterations |
  111. | `gpt-5` | ✅ | `medium` | Deep research |
  112. | `gpt-5-nano` | ✅ | `medium` | Balanced approach |
  113. | `o3` | ✅ | `medium` | Advanced reasoning |
  114. | `o4-mini` | ✅ | `medium` | Efficient reasoning |
  115. ## 📦 Installation
  116. ### Using uvx (Recommended)
  117. ```bash
  118. # Install and run directly
  119. uvx openai-websearch-mcp
  120. # Or install globally
  121. uvx install openai-websearch-mcp
  122. ```
  123. ### Using pip
  124. ```bash
  125. # Install from PyPI
  126. pip install openai-websearch-mcp
  127. # Run the server
  128. python -m openai_websearch_mcp
  129. ```
  130. ### From Source
  131. ```bash
  132. # Clone the repository
  133. git clone https://github.com/yourusername/openai-websearch-mcp.git
  134. cd openai-websearch-mcp
  135. # Install dependencies
  136. uv sync
  137. # Run in development mode
  138. uv run python -m openai_websearch_mcp
  139. ```
  140. ## 👩‍💻 Development
  141. ### Setup Development Environment
  142. ```bash
  143. # Clone and setup
  144. git clone https://github.com/yourusername/openai-websearch-mcp.git
  145. cd openai-websearch-mcp
  146. # Create virtual environment and install dependencies
  147. uv sync
  148. # Run tests
  149. uv run python -m pytest
  150. # Install in development mode
  151. uv pip install -e .
  152. ```
  153. ### Environment Variables
  154. | Variable | Description | Default |
  155. |----------|-------------|---------|
  156. | `OPENAI_API_KEY` | Your OpenAI API key | *Required* |
  157. | `OPENAI_DEFAULT_MODEL` | Default model to use | `gpt-5-mini` |
  158. ## 🐛 Debugging
  159. ### Using MCP Inspector
  160. ```bash
  161. # For uvx installations
  162. npx @modelcontextprotocol/inspector uvx openai-websearch-mcp
  163. # For pip installations
  164. npx @modelcontextprotocol/inspector python -m openai_websearch_mcp
  165. ```
  166. ### Common Issues
  167. **Issue**: "Unsupported parameter: 'reasoning.effort'"
  168. **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.
  169. **Issue**: "No module named 'openai_websearch_mcp'"
  170. **Solution**: Ensure you've installed the package correctly and your Python path includes the package location.
  171. ## 📄 License
  172. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  173. ## 🙏 Acknowledgments
  174. - 🤖 Generated with [Claude Code](https://claude.ai/code)
  175. - 🔥 Powered by [OpenAI's Web Search API](https://openai.com)
  176. - 🛠️ Built on the [Model Context Protocol](https://modelcontextprotocol.io/)
  177. ---
  178. **Co-Authored-By**: Claude <noreply@anthropic.com>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.