JJsilvera1/OpenAI-WebSearch-MCP

OpenAI Web Search MCP Server

A Model Context Protocol (MCP) server that provides real-time web search capabilities using OpenAI's gpt-4o-mini-search-preview model. This server enables Claude Code, Claude Desktop, and other MCP clients to perform current web searches with automatic citations and location-aware results.

Features

• 🌐 Real-time web search using OpenAI's latest search-enabled model
• 📚 Automatic citations with source URLs and titles
• 🌍 Location-aware searches with country/city/region support
• ⚡ Configurable search context (low/medium/high) for speed vs depth
• 🔒 Secure API key handling through environment variables
• 🎯 Domain-specific searches for current information, pricing, availability checks

Installation

Prerequisites

• Python 3.8 or higher
• OpenAI API key with access to gpt-4o-mini-search-preview model

Quick Install

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

# Install dependencies
pip install -r requirements.txt

# Set your OpenAI API key
export OPENAI_API_KEY="your-openai-api-key-here"

Using pip (when published)

pip install openai-websearch-mcp

Configuration

Claude Desktop

Add to your Claude Desktop configuration file (~/.claude/claude.json):

{
  "mcpServers": {
    "openai-web-search": {
      "command": "python",
      "args": ["/path/to/openai-websearch-mcp/server.py"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

Claude Code

Add to your Claude Code configuration (~/.claude/claude.json):

{
  "projects": {
    "*": {
      "mcpServers": {
        "openai-web-search": {
          "command": "python",
          "args": ["/path/to/openai-websearch-mcp/server.py"],
          "env": {
            "OPENAI_API_KEY": "your-openai-api-key-here"
          }
        }
      },
      "allowedTools": [
        "mcp__openai_web_search__openai_web_search"
      ]
    }
  }
}

Other MCP Clients

The server follows the standard MCP protocol and can be used with any MCP-compatible client by configuring it to run the server.py script with the appropriate environment variables.

Usage

Basic Search

Once configured, you can use the web search functionality through your MCP client:

Search for "current Bitcoin price"

Location-Aware Search

Search for "best restaurants" with location "New York", "NY", "US"

Context Control

• Low context: Fastest searches for quick answers
• Medium context: Balanced speed and comprehensiveness (default)
• High context: Most comprehensive results for complex queries

Tool Parameters

The openai_web_search tool accepts the following parameters:

Examples

Current Information

• "What's the current weather in London?"
• "Latest news about OpenAI"
• "Bitcoin price today"

Domain Research

• "Check domain availability for example.com"
• "Domain registration pricing"

Market Research

• "Current stock price for AAPL"
• "AWS pricing for EC2 instances"
• "iPhone 15 availability"

Location-Specific

• "Best coffee shops in Seattle" (with city: "Seattle", region: "WA", country: "US")
• "Current time in Tokyo" (with city: "Tokyo", country: "JP")

Response Format

The server returns search results with:

1. Main Content: Comprehensive answer to your query
2. Sources: Automatic citations with clickable links
3. Metadata: Search context and model information

Example response:

The current Bitcoin price is $67,234.52 USD, up 2.3% in the last 24 hours...

📚 Sources:
1. [CoinGecko - Bitcoin Price](https://www.coingecko.com/en/coins/bitcoin)
2. [CoinMarketCap - BTC](https://coinmarketcap.com/currencies/bitcoin/)

Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run with coverage
pytest tests/ --cov=server

Code Formatting

# Format code
black server.py

# Check linting
flake8 server.py

# Type checking
mypy server.py

Testing the Server

You can test the server directly:

# Set your API key
export OPENAI_API_KEY="your-api-key"

# Test the server
python server.py

Troubleshooting

Common Issues

1. "OPENAI_API_KEY environment variable not set"

   • Ensure your OpenAI API key is properly set in the environment
   • Verify the key has access to gpt-4o-mini-search-preview model

2. "Server timeout" or connection issues

   • Check your internet connection
   • Verify OpenAI API status
   • Try reducing context_size to "low" for faster responses

3. "Tool not found" in Claude

   • Ensure the MCP server is properly configured in your client
   • Verify the tool name is correctly added to allowedTools
   • Restart your MCP client after configuration changes

4. Unicode/encoding errors on Windows

   • This is a display issue and doesn't affect functionality
   • The search results are still accurate

Debug Mode

Enable debug logging by setting:

export PYTHONPATH="."
export OPENAI_LOG=debug
python server.py

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Built on the Model Context Protocol
• Powered by OpenAI's search-enabled models
• Designed for seamless integration with Claude Code and Claude Desktop

Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: See the docs/ directory for detailed guides

Note: This is an independent project and is not officially affiliated with OpenAI or Anthropic.