# OpenAI WebSearch MCP Server (TypeScript) 🔍
[](https://www.typescriptlang.org/)
[](https://bun.sh)
[](https://modelcontextprotocol.io/)
[](https://opensource.org/licenses/MIT)
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](https://modelcontextprotocol.io/) 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](#-features)
- [Quick Start](#-quick-start)
- [Configuration](#️-configuration)
- [Usage Examples](#-usage-examples)
- [Model Selection Guide](#-model-selection-guide)
- [Development](#-development)
- [Debugging](#-debugging)
- [Project Structure](#️-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](https://bun.sh)** runtime (v1.2 or higher)
```bash
curl -fsSL https://bun.sh/install | bash
```
2. **OpenAI API Key** with Web Search API access
- Get your API key from [OpenAI Platform](https://platform.openai.com/api-keys)
- Ensure your account has access to the Web Search API
### Installation
```bash
# 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:
```bash
# 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:
```env
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)**
```json
{
"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)**
```json
{
"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**
```json
{
"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:**
```bash
npx -y openai-websearch-mcp
```
**Using bunx:**
```bash
bunx openai-websearch-mcp
```
**Local development:**
```bash
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
```bash
# 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](https://www.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
```bash
# 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:
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:
```bash
# 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`):
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:
```bash
# 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:
```bash
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:
```bash
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:
```bash
curl -fsSL https://bun.sh/install | bash
```
### Logging
The server logs to stderr. To see detailed logs:
```bash
# Run with output visible
bun run src/index.ts 2>&1 | tee server.log
```
### Testing Individual Components
```bash
# 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](LICENSE) file for details.
## 🙏 Acknowledgments
- 🔥 Powered by [OpenAI's Web Search API](https://openai.com)
- 🛠️ Built on the [Model Context Protocol](https://modelcontextprotocol.io/)
- ⚡ Runtime by [Bun](https://bun.sh)
- 🐍 Inspired by [ConechoAI's Python implementation](https://github.com/ConechoAI/openai-websearch-mcp)
