OpenAI Search MCP

English | 简体中文

🚀 Integrate OpenAI-compatible API's powerful search capabilities into Claude via MCP protocol, break through knowledge limitations, and access real-time information

Features • Quick Start • Usage • Troubleshooting

📖 Overview

OpenAI Search MCP is a high-performance Node.js/TypeScript implementation of an MCP (Model Context Protocol) server that integrates OpenAI-compatible API's powerful capabilities to provide real-time web search and web content extraction for Claude, Claude Code, and other AI assistants.

✨ Key Features

• 🌐 Real-time Web Search - Break through AI knowledge cutoff and access the latest information
• 🔍 Smart Web Fetching - Extract complete web content and convert to structured Markdown
• 🔄 Auto Retry Mechanism - Intelligently handle network fluctuations and temporary errors
• 📦 Plug & Play - Run with single npx command, no complex configuration needed
• ⚡ High Performance - Cold start < 1 second, memory footprint < 30MB
• 🔒 Type Safety - Complete TypeScript type definitions
• 🛠️ Fetch Polyfill - Compatible with all Node.js 18+ environments

🎯 Why Choose OpenAI Search MCP?

| Feature | Official WebSearch | OpenAI Search MCP | |---------|-------------------|-----------------| | Search Quality | Generic | AI Enhanced 🧠 | | Web Fetching | Basic | Deep Extraction 📄 | | Startup Speed | Slower | < 1 second ⚡ | | Customization | Fixed | Highly Configurable ⚙️ | | Cost | Paid | Use Your Own API Key 💰 |

🚀 Quick Start

Prerequisites

• Node.js 18+ (with fetch API and ES Modules support)
• OpenAI-compatible API - This project uses the OpenAI API format. You need:
  • An API endpoint (e.g., OpenAI-compatible service)
  • An API key for that endpoint
• Claude Desktop (optional, for GUI integration)

Option 1: Using npx (Recommended)

No installation required, run the latest version directly:

npx openai-search-mcp

Option 2: Global Installation

npm install -g openai-search-mcp
openai-search

⚙️ Configure Claude Desktop

Step 1: Get API Endpoint and Key

This project uses the OpenAI API format. You need an API endpoint that is compatible with OpenAI's API specification.

Options:

1. OpenAI-compatible API: Use any service that provides OpenAI-compatible endpoints
2. Other OpenAI-compatible APIs: Any service that follows the OpenAI API format

You will need:

• OPENAI_API_URL: Your API endpoint URL (e.g., https://api.openai.com/v1)
• OPENAI_API_KEY: Your API key for that endpoint
• OPENAI_MODEL: The model identifier (default: gpt-4o)

Step 2: Configure Environment Variables

Edit ~/.config/claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%\claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "openai-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "openai-search-mcp"],
      "env": {
        "OPENAI_API_URL": "https://api.openai.com/v1",
        "OPENAI_API_KEY": "your-api-key-here",
        "OPENAI_MODEL": "gpt-4o"
      }
    }
  }
}

Important:

• Replace https://your-api-endpoint.com/v1 with your actual API endpoint
• Replace your-api-key-here with your actual API key
• The endpoint must be OpenAI-compatible

Step 3: Restart Claude Desktop

After configuration, completely quit and restart Claude Desktop.

Step 4: Verify Installation

In Claude conversation, type:

Show openai-search config info

Or

Search for latest TypeScript 5.5 features

🛠️ Available Tools

1️⃣ web_search - Web Search

Execute intelligent search and return structured results.

Parameters:

• query (required) - Search keywords
• platform (optional) - Specify platform like "github", "stackoverflow"
• min_results (optional) - Minimum results, default 3
• max_results (optional) - Maximum results, default 10

Usage Examples:

Search for latest Next.js 15 updates
Search TypeScript 5.5 new features, return 5 results
Search for openai-search projects on GitHub

2️⃣ web_fetch - Web Fetching

Extract complete content from specified URL and convert to Markdown format.

Parameters:

• url (required) - Web page URL to fetch

Usage Examples:

Fetch README content from https://github.com/lie5860/openai-search-mcp
Get complete documentation from https://www.typescriptlang.org/docs

3️⃣ get_config_info - Configuration Diagnostics

Get current configuration and connection status.

Returns:

• API URL and model configuration
• Connection test results
• Response time and available model information

Usage Examples:

Show openai-search config info

4️⃣ switch_model - Model Switching

Dynamically switch AI models.

Parameters:

• model (required) - Model ID (e.g., "gpt-4o", "gpt-4o-mini")

Usage Examples:

Switch to gpt-4o-mini model
Switch model to gpt-4o

5️⃣ toggle_builtin_tools - Tool Management

Disable/Enable Claude's built-in search tools.

Parameters:

• action (optional) - "on" disable built-in tools, "off" enable built-in tools, "status" view status

Usage Examples:

Disable official WebSearch tool
View current tool status

💻 Development Guide

Building from Source

# Clone repository
git clone https://github.com/lie5860/openai-search-mcp.git
cd openai-search-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run development server
npm run dev

# Run tests
npm test

Project Structure

openai-search-mcp/
├── src/
│   ├── server.ts          # MCP server main entry
│   ├── config/            # Configuration management
│   ├── providers/         # OpenAI-compatible API provider
│   ├── utils/             # Utilities (fetch polyfill, retry, logger)
│   └── types/             # TypeScript type definitions
├── bin/
│   └── openai-search.js   # CLI command entry
├── dist/                  # Build output directory
├── package.json
├── tsconfig.json
└── README.md

Tech Stack

• Runtime: Node.js 18+
• Language: TypeScript 5.5+
• MCP SDK: @modelcontextprotocol/sdk ^1.0.4
• HTTP Client: Fetch API + Undici (auto polyfill)
• Config Management: dotenv
• Module System: ES Modules (ESM)

🔧 Environment Variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | OPENAI_API_URL | OpenAI-compatible API endpoint | Yes | - | | OPENAI_API_KEY | API key for your endpoint | Yes | - | | OPENAI_MODEL | Model identifier | No | gpt-4o | | DEBUG | Debug mode | No | false | | OPENAI_LOG_LEVEL | Log level | No | INFO |

🔥 Troubleshooting

❌ Issue 1: Connection Failed

Error: ❌ Connection failed or API error

Solutions:

1. Check if OPENAI_API_URL is correct and points to an OpenAI-compatible endpoint
2. Verify if OPENAI_API_KEY is valid for your API provider
3. Confirm network connection is working
4. Use get_config_info tool for diagnostics

❌ Issue 2: Module Not Found

Error: Cannot find module

Solutions:

# Reinstall dependencies
npm install

# Rebuild
npm run build

❌ Issue 3: Permission Error

Error: EACCES

Solutions:

# Linux/macOS use sudo
sudo npm install -g openai-search-mcp

# Or recommend using npx (no permissions needed)
npx openai-search-mcp

❌ Issue 4: fetch is not defined

Error: ReferenceError: fetch is not defined

Cause: fetch API not properly initialized in Node.js environment

Solutions:

1. Check Node.js version:

node --version  # Should be >= 18.0.0

2. Ensure using latest version (v1.0.1+ includes fetch polyfill):

npm update openai-search-mcp
# Or use npx directly
npx openai-search-mcp

3. If problem persists, please file an issue: https://github.com/lie5860/openai-search-mcp/issues

📝 Advanced Configuration

Claude Desktop Prompt Optimization

Edit ~/.claude/CLAUDE.md and add the following for better experience:

# OpenAI Search MCP Usage Guide

## Activation
- Prioritize OpenAI Search for web search needs
- Auto-activate when latest information is needed
- Use web_fetch for web content extraction

## Tool Selection Strategy
| Scenario | Recommended Tool | Parameters |
|----------|-----------------|------------|
| Quick search | web_search | min_results=3, max_results=5 |
| Deep research | web_search + web_fetch | Search first, then fetch key pages |
| Specific platform | web_search | Set platform parameter |
| Complete docs | web_fetch | Fetch URL directly |

## Output Guidelines
- **Must cite sources**: `[Title](URL)`
- **Time-sensitive info**: Note retrieval date
- **Multi-source validation**: Cross-validate important info
- **No fabrication**: Clearly state when no results found

## Error Handling
- No results → Relax query or change keywords
- Connection failed → Use get_config_info to diagnose
- Timeout → Reduce max_results or retry

📊 Performance Comparison

| Metric | Python Version | Node.js Version (This Project) | |--------|---------------|-------------------------------| | Cold Start | ~2-3 seconds | < 1 second ⚡ | | Memory Usage | ~50MB | < 30MB 💾 | | Package Size | ~15MB | ~5MB 📦 | | Type Safety | Type hints | Full TypeScript 🔒 | | Deployment | Needs virtual env | npx one-click run 🚀 |

🤝 Contributing

Contributions, issues, and feature requests are welcome!

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

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• Model Context Protocol - Powerful AI context protocol
• Claude - Excellent AI assistant by Anthropic

🌟 Tribute to Original Project

This project is based on GuDaStudio/GrokSearch (MIT License). Big thanks to the original author for the excellent work!

Key Changes:

• ✅ Migrated from Python to TypeScript/Node.js
• ✅ Added Fetch Polyfill for better environment compatibility
• ✅ Optimized project structure and modular design
• ✅ Complete TypeScript type definitions
• ✅ Faster startup speed and smaller package size

Important Note: This project uses the OpenAI API format and requires an OpenAI-compatible API endpoint.

The original project (Python version) is equally excellent. If you're more familiar with the Python ecosystem, we recommend using the original version:

• 🔗 GuDaStudio/GrokSearch

📮 Contact

• GitHub: https://github.com/lie5860/openai-search-mcp
• Issues: https://github.com/lie5860/openai-search-mcp/issues
• NPM: https://www.npmjs.com/package/openai-search-mcp

If this project helps you, please give it a ⭐️ Star!

Made with ❤️ by lie5860