OpenAI WebSearch MCP Server (TypeScript) 🔍

A TypeScript MCP server that provides intelligent web search capabilities using OpenAI's reasoning models and Web Search API. Built with Bun for blazing-fast performance.

What is MCP? The Model Context Protocol allows AI assistants like Claude to connect to external tools and data sources. This server adds web search capabilities to your AI assistant.

Table of Contents

• Features

• Quick Start

• Configuration

• Usage Examples

• Model Selection Guide

• Development

• Debugging

• Project Structure

✨ Features

• 🔍 OpenAI Web Search API: Direct integration with OpenAI's Web Search API

• 🌍 Localized Results: Support for location-based search customization

• 📝 Rich Type Safety: Full TypeScript types for all parameters and responses

• 🚀 Bun-Powered: Lightning-fast runtime and package management

• 🔧 Flexible Configuration: Environment variable support for easy deployment

• 📚 Source Citations: Automatic extraction and formatting of web sources

🚀 Quick Start

Prerequisites

1. Bun runtime (v1.2 or higher)

   curl -fsSL https://bun.sh/install | bash

2. OpenAI API Key with Web Search API access

   • Get your API key from OpenAI Platform

   • Ensure your account has access to the Web Search API

Installation

Testing the Server

Before integrating with an MCP client, test that the server works:

If the server starts successfully, you'll see:

⚙️ Configuration

Environment Variables

The server requires the following environment variables:

Create a .env file in the project root:

MCP Client Configuration

Configure your MCP client to connect to this server. Choose either the published package (recommended) or local development setup.

Claude Desktop

1. Find your config file location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this server configuration:

Option 1: Using npx (recommended for published package)

Option 2: Using bunx (alternative for Bun users)

Option 3: Local development setup

3. Restart Claude Desktop

4. Look for the 🔌 icon in Claude to verify the server is connected

Cursor

1. Open Cursor Settings (Cmd/Ctrl + ,)

2. Search for "MCP" in settings

3. Add server configuration (same format as Claude Desktop above)

4. Restart Cursor

Other MCP Clients

Any MCP-compatible client can use this server with the stdio transport:

Using npx:

Using bunx:

Local development:

🛠️ Available Tools

openai_web_search

Performs intelligent web search with AI reasoning capabilities.

Parameters

Supported Models

All models support OpenAI's Web Search API:

• gpt-4o-search-preview - High-quality web search with comprehensive results (default)

• gpt-4o-mini-search-preview - Faster web search with efficient performance

• gpt-5-search-api - Advanced search capabilities

💬 Usage Examples

Once configured in your MCP client (Claude Desktop, Cursor, etc.), simply ask questions that require web search:

Quick Search

The AI assistant will automatically use openai_web_search with the default model.

Localized Search

You can provide location context for more relevant local results.

Specific Model Selection

Choose a specific model for your search needs (speed vs quality trade-off).

Common Use Cases

• 📰 News & Current Events: "What happened in tech news today?"

• 📊 Research: "Latest papers on transformer architectures"

• 🗺️ Local Information: "Best coffee shops near me"

• 💻 Technical Documentation: "FastAPI async database patterns"

• 🎯 Product Research: "Compare M3 MacBook Pro vs Air"

• 📈 Market Data: "Current AI startup funding trends"

🤖 Model Selection Guide

Standard Web Search (Default)

• Recommended: gpt-4o-search-preview (default)

• Use Case: General web search, current information, comprehensive results

• Benefits: High-quality responses with source citations

Fast Web Search

• Recommended: gpt-4o-mini-search-preview

• Use Case: Quick queries, real-time information, faster responses

• Benefits: Lower latency, cost-effective for frequent searches

Advanced Search

• Recommended: gpt-5-search-api

• Use Case: Complex search queries, advanced capabilities

• Benefits: Latest search features and capabilities

📦 Development

📤 Publishing to NPM

Prerequisites

1. NPM Account: Create one at npmjs.com/signup if you don't have one

2. Email Verified: Ensure your NPM account email is verified

Before Publishing

1. Update package.json metadata:

   • Replace YOUR_USERNAME in repository.url with your GitHub username

   • Replace YOUR_USERNAME in homepage with your GitHub username

   • Replace YOUR_USERNAME in bugs.url with your GitHub username

   • Optionally add author field: "author": "Your Name <your.email@example.com>"

2. Remove any test dependencies:

   • Check for any file: references in dependencies

   • Remove test tarballs from the project directory

Publishing Steps

What Happens During Publish

The prepublishOnly script automatically runs:

1. bun run typecheck - Verifies TypeScript types

2. bun run build - Builds the dist/ folder

3. NPM packages and uploads only files in the files array (dist/, README.md, LICENSE)

After Publishing

• Your package will be available at: https://www.npmjs.com/package/openai-websearch-mcp

• Users can install it with: npx openai-websearch-mcp or bunx openai-websearch-mcp

• It will appear in NPM search results

Publishing Updates

When you need to publish a new version:

Optional: Scoped Package

To publish under your username (e.g., @yourusername/openai-websearch-mcp):

1. Change "name" in package.json to "@yourusername/openai-websearch-mcp"

2. Publish with: npm publish --access public

Verify Publication

After publishing, verify your package:

🏗️ Project Structure

🐛 Debugging & Troubleshooting

Using MCP Inspector

The MCP Inspector provides a web UI for testing your server:

This will open a browser interface where you can:

• See available tools

• Test tool calls with different parameters

• View request/response logs

• Debug errors

Common Issues

"OPENAI_API_KEY environment variable is required"

Solution: Create a .env file with your API key:

"Invalid OpenAI API key format"

Solution: Ensure your API key starts with sk-

"Server not appearing in Claude Desktop"

Solutions:

1. Verify the absolute path in your config is correct

2. Restart Claude Desktop completely

3. Check Claude's logs:

   • macOS: ~/Library/Logs/Claude/

   • Windows: %APPDATA%\Claude\logs\

   • Linux: ~/.config/Claude/logs/

"Command 'bun' not found"

Solution: Install Bun:

Logging

The server logs to stderr. To see detailed logs:

Testing Individual Components

📄 License

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

🙏 Acknowledgments

• 🔥 Powered by OpenAI's Web Search API

• 🛠️ Built on the Model Context Protocol

• ⚡ Runtime by Bun

• 🐍 Inspired by ConechoAI's Python implementation