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
-
Bun runtime (v1.2 or higher)
curl -fsSL https://bun.sh/install | bash -
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/yourusername/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
-
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
- macOS:
-
Add this server configuration:
Option 1: Using npx (recommended for published package)
{
"mcpServers": {
"openai-websearch-mcp": {
"command": "npx",
"args": ["-y", "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": ["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"
}
}
}
}
-
Restart Claude Desktop
-
Look for the 🔌 icon in Claude to verify the server is connected
Cursor
- Open Cursor Settings (
Cmd/Ctrl + ,) - Search for "MCP" in settings
- Add server configuration (same format as Claude Desktop above)
- Restart Cursor
Other MCP Clients
Any MCP-compatible client can use this server with the stdio transport:
Using npx:
npx -y openai-websearch-mcp
Using bunx:
bunx 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 performancegpt-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
- NPM Account: Create one at npmjs.com/signup if you don't have one
- Email Verified: Ensure your NPM account email is verified
Before Publishing
-
Update package.json metadata:
- Replace
YOUR_USERNAMEinrepository.urlwith your GitHub username - Replace
YOUR_USERNAMEinhomepagewith your GitHub username - Replace
YOUR_USERNAMEinbugs.urlwith your GitHub username - Optionally add
authorfield:"author": "Your Name <your.email@example.com>"
- Replace
-
Remove any test dependencies:
- Check for any
file:references in dependencies - Remove test tarballs from the project directory
- Check for any
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!
npm publish
What Happens During Publish
The prepublishOnly script automatically runs:
bun run typecheck- Verifies TypeScript typesbun run build- Builds the dist/ folder- NPM packages and uploads only files in the
filesarray (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-mcporbunx 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
Optional: Scoped Package
To publish under your username (e.g., @yourusername/openai-websearch-mcp):
- Change
"name"in package.json to"@yourusername/openai-websearch-mcp" - Publish with:
npm publish --access public
Verify Publication
After publishing, verify your package:
# Check package info
npm info openai-websearch-mcp
# Test installation
npx 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:
- Verify the absolute path in your config is correct
- Restart Claude Desktop completely
- Check Claude's logs:
- macOS:
~/Library/Logs/Claude/ - Windows:
%APPDATA%\Claude\logs\ - Linux:
~/.config/Claude/logs/
- macOS:
"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