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

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

# 2. Install dependencies
bun install

# 3. Set up environment variables
cp .env.example .env

# 4. Edit .env and add your OpenAI API key
# OPENAI_API_KEY=sk-your-api-key-here
# OPENAI_DEFAULT_MODEL=gpt-5-mini

Testing the Server

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

# Run the server directly (it will wait for MCP protocol messages)
bun run start

# Or test with MCP Inspector (recommended)
bunx @modelcontextprotocol/inspector bun run src/index.ts

If the server starts successfully, you'll see:

openai-websearch-mcp v1.0.0 running on stdio
Default model: gpt-4o-search-preview

⚙️ Configuration

Environment Variables

The server requires the following environment variables:

| Variable | Description | Required | Default | |------------------------|----------------------|----------|-------------------------| | OPENAI_API_KEY | Your OpenAI API key | Yes | - | | OPENAI_DEFAULT_MODEL | Default model to use | No | gpt-4o-search-preview |

Create a .env file in the project root:

OPENAI_API_KEY=sk-your-api-key-here
OPENAI_DEFAULT_MODEL=gpt-4o-search-preview

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)

{
  "mcpServers": {
    "openai-websearch-mcp": {
      "command": "npx",
      "args": ["-y", "@luchini/openai-websearch-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key-here",
        "OPENAI_DEFAULT_MODEL": "gpt-4o-search-preview"
      }
    }
  }
}

Option 2: Using bunx (alternative for Bun users)

{
  "mcpServers": {
    "openai-websearch-mcp": {
      "command": "bunx",
      "args": ["@luchini/openai-websearch-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key-here",
        "OPENAI_DEFAULT_MODEL": "gpt-4o-search-preview"
      }
    }
  }
}

Option 3: Local development setup

{
  "mcpServers": {
    "openai-websearch-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/openai-websearch-mcp/src/index.ts"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key-here",
        "OPENAI_DEFAULT_MODEL": "gpt-4o-search-preview"
      }
    }
  }
}

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:

npx -y @luchini/openai-websearch-mcp

Using bunx:

bunx @luchini/openai-websearch-mcp

Local development:

bun run /absolute/path/to/openai-websearch-mcp/src/index.ts

🛠️ Available Tools

openai_web_search

Performs intelligent web search with AI reasoning capabilities.

Parameters

| Parameter | Type | Required | Description | Default | |-----------------|----------|----------|------------------------------------------------------------------------------------------|-------------------------| | input | string | Yes | The search query or question | - | | model | string | No | AI model to use | gpt-4o-search-preview | | user_location | object | No | Location for localized results (must include type: "approximate" with country/city/region) | null |

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

"What are the latest developments in AI?"

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

Localized Search

"What tech meetups are happening in San Francisco this week?"

You can provide location context for more relevant local results.

Specific Model Selection

"Use gpt-4o-mini-search-preview to search for: Python async best practices"

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

# Install dependencies
bun install

# Run in development mode with auto-reload
bun run dev

# Build for production
bun run build

# Run tests
bun test

# Type checking
bun run typecheck

# Lint code
bun run lint

📤 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

Publishing Steps

# 1. Login to NPM (one-time setup)
npm login
# Enter your username, password, and email when prompted

# 2. Verify you're logged in
npm whoami

# 3. Check what will be published (dry run)
npm publish --dry-run

# 4. Publish to NPM as a scoped package!
npm publish --access public

Note: The --access public flag is required for scoped packages (packages starting with @username/) to make them publicly available.

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/@luchini/openai-websearch-mcp
• Users can install it with: npx @luchini/openai-websearch-mcp or bunx @luchini/openai-websearch-mcp
• It will appear in NPM search results

Publishing Updates

When you need to publish a new version:

# Update version (choose one)
npm version patch  # Bug fixes: 1.0.0 -> 1.0.1
npm version minor  # New features: 1.0.0 -> 1.1.0
npm version major  # Breaking changes: 1.0.0 -> 2.0.0

# Publish the new version
npm publish --access public

Verify Publication

After publishing, verify your package:

# Check package info
npm info @luchini/openai-websearch-mcp

# Test installation
npx @luchini/openai-websearch-mcp@latest

🏗️ Project Structure

openai-websearch-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types/
│   │   ├── openai.ts         # OpenAI API types
│   │   ├── mcp.ts            # MCP tool types
│   │   └── config.ts         # Configuration types
│   ├── tools/
│   │   └── webSearch.ts      # Web search tool implementation
│   ├── utils/
│   │   ├── config.ts         # Environment config handler
│   │   ├── models.ts         # Model validation & defaults
│   │   └── errors.ts         # Error handling utilities
│   └── constants.ts          # Model lists, defaults
├── package.json
├── tsconfig.json
└── README.md

🐛 Debugging & Troubleshooting

Using MCP Inspector

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

bunx @modelcontextprotocol/inspector bun run src/index.ts

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:

echo "OPENAI_API_KEY=sk-your-key-here" > .env

"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:

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

Logging

The server logs to stderr. To see detailed logs:

# Run with output visible
bun run src/index.ts 2>&1 | tee server.log

Testing Individual Components

# Type checking
bun run typecheck

# Run specific tests (if implemented)
bun test

# Check if OpenAI API key works
# (Creates a simple test script to verify)
echo 'import OpenAI from "openai"; const client = new OpenAI(); console.log("API key valid");' | bun run -

📄 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