使用说明

OpenAI WebSearch MCP服务器（TypeScript）🔍

TypeScript MCP服务器，使用OpenAI的推理模型和web搜索API提供智能web搜索功能。采用Bun制造，性能超快。

什么是MCP？ 这模型上下文协议允许像Claude这样的人工智能助手连接到外部工具和数据源。此服务器为您的AI助手添加了网络搜索功能。

✨ 特性

🔍 OpenAI Web搜索API：与OpenAI的Web搜索API直接集成
🌍 本地化结果：支持基于位置的搜索自定义
📝 丰富的类型安全：所有参数和响应的完整TypeScript类型
🚀 Bun供电：闪电般快速的运行时间和包管理
🔧 灵活的配置：环境变量支持，便于部署
📚 来源引用：自动提取和格式化网络资源

🚀 快速开始

先决条件

包子运行时（v1.2或更高版本）
```
curl -fsSL https://bun.sh/install | bash
```
OpenAI API密钥 使用Web搜索API访问
- 从获取API密钥 OpenAI平台
- 确保您的帐户可以访问Web搜索API

安装

# 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

测试服务器

在与MCP客户端集成之前，请测试服务器是否正常工作：

# 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

如果服务器成功启动，您将看到：

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

⚙️ 配置

环境变量

服务器需要以下环境变量：

变量	描述	必填	默认
`OPENAI_API_KEY`	您的OpenAI API密钥	是	-
`OPENAI_DEFAULT_MODEL`	要使用的默认模型	否	`gpt-4o-search-preview`

创建一个 .env 项目根目录中的文件：

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

MCP客户端配置

配置您的MCP客户端以连接到此服务器。选择已发布的软件包（推荐）或本地开发设置。

克劳德桌面

查找您的配置文件位置：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- 视窗: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
添加此服务器配置：

选项1：使用npx（建议用于已发布的软件包）

{
  "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"
      }
    }
  }
}

选项2：使用丁腈橡胶（丁腈橡胶用户的替代品）

{
  "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"
      }
    }
  }
}

选项3：当地发展设置

{
  "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"
      }
    }
  }
}

重新启动克劳德桌面
寻找🔌 Claude中的图标，用于验证服务器是否已连接

光标

打开光标设置(Cmd/Ctrl + ,)
在设置中搜索“MCP”
添加服务器配置（格式与上述Claude Desktop相同）
重新启动游标

其他MCP客户端

任何兼容MCP的客户端都可以将此服务器与stdio传输一起使用：

使用npx：

npx -y openai-websearch-mcp

使用bunx：

bunx openai-websearch-mcp

地方发展：

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

🛠️ 可用工具

`openai_web_search`

使用AI推理功能执行智能网络搜索。

参数

参数	类型	必填	说明	默认
`input`	`string`	是	搜索查询或问题	-
`model`	`string`	否	要使用的AI模型	`gpt-4o-search-preview`
`user_location`	`object`	否	本地化结果的位置（必须包括 `type: "approximate"` 国家/城市/地区）	`null`

支持的型号

所有模型都支持OpenAI的Web搜索API：

gpt-4o-search-preview -具有全面结果的高质量网络搜索（默认）
gpt-4o-mini-search-preview -更快的网络搜索和高效的性能
gpt-5-search-api -高级搜索功能

💬 用法示例

在MCP客户端（Claude Desktop、Cursor等）中配置后，只需提出需要网络搜索的问题：

快速搜索

"What are the latest developments in AI?"

AI助手将自动使用 openai_web_search 使用默认模型。

本地化搜索

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

您可以为更相关的本地结果提供位置上下文。

具体型号选择

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

为您的搜索需求选择一个特定的模型（速度与质量权衡）。

常见用例

📰 新闻与时事：“今天科技新闻发生了什么？”
📊 研究：“关于变压器架构的最新论文”
🗺️ 本地信息：“我附近最好的咖啡馆”
💻 技术文档：“FastAPI异步数据库模式”
🎯 产品研究：“比较M3 MacBook Pro与Air”
📈 市场数据：“当前人工智能初创公司的融资趋势”

🤖 选型指南

标准Web搜索（默认）

推荐: gpt-4o-search-preview （默认）
用例：一般网络搜索、最新信息、综合结果
益处：引用来源的高质量回复

快速网络搜索

推荐: gpt-4o-mini-search-preview
用例：快速查询、实时信息、更快的响应
益处：延迟更低，对于频繁搜索更具成本效益

高级搜索

推荐: gpt-5-search-api
用例：复杂的搜索查询，高级功能
益处：最新的搜索特性和功能

📦 发展

# 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

📤 向NPM发布

先决条件

NPM账户：创建一个 npmjs.com/注册如果你没有
电子邮件已验证：确保您的NPM帐户电子邮件已验证

出版前

更新package.json元数据:
- 替换 YOUR_USERNAME 在 repository.url 使用您的GitHub用户名
- 替换 YOUR_USERNAME 在 homepage 使用您的GitHub用户名
- 替换 YOUR_USERNAME 在 bugs.url 使用您的GitHub用户名
- 可选择添加 author 字段： "author": "Your Name <your.email@example.com>"
删除所有测试依赖项:
- 检查是否有 file: 依赖关系中的引用
- 从项目目录中删除测试tarball

发布步骤

# 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

发布过程中会发生什么

这 prepublishOnly 脚本自动运行：

bun run typecheck -验证TypeScript类型
bun run build -构建dist/文件夹
NPM包和仅上传文件 files 数组（dist/、README.md、许可证）

发布后

您的包裹将在以下地点提供： https://www.npmjs.com/package/openai-websearch-mcp
用户可以通过以下方式安装： npx openai-websearch-mcp 或 bunx openai-websearch-mcp
它将出现在NPM搜索结果中

发布更新

当您需要发布新版本时：

# 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

可选：范围包

以您的用户名发布（例如。， @yourusername/openai-websearch-mcp):

改变 "name" 在package.json中 "@yourusername/openai-websearch-mcp"
发布方式： npm publish --access public

验证发布

发布后，验证您的包：

# Check package info
npm info openai-websearch-mcp

# Test installation
npx openai-websearch-mcp@latest

🏗️ 项目结构

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

🐛 调试与故障排除

使用MCP检查器

MCP检查器提供了一个用于测试服务器的web UI：

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

这将打开一个浏览器界面，您可以在其中：

查看可用工具
具有不同参数的测试工具调用
查看请求/响应日志
调试错误

常见问题

“OPENAI_API_KEY环境变量是必需的”

解决方案：创建一个 .env 使用API密钥文件：

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

“无效的OpenAI API密钥格式”

解决方案：确保您的API密钥以 sk-

“服务器未出现在Claude Desktop中”

解决方案:

验证配置中的绝对路径是否正确
完全重新启动克劳德桌面
查看克劳德的日志：
- macOS： ~/Library/Logs/Claude/
- 窗户： %APPDATA%\Claude\logs\
- Linux： ~/.config/Claude/logs/

“找不到命令'bun'”

解决方案：安装Bun：

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

日志记录

服务器记录到stderr。查看详细日志：

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

测试单个组件

# 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 -

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

🔥 由...驱动 OpenAI的Web搜索API
🛠️ 建立在模型上下文协议
⚡ 运行时间由包子
🐍 灵感来自 ConechoAI的Python实现

使用说明

OpenAI WebSearch MCP服务器（TypeScript）🔍

目录

✨ 特性

🚀 快速开始

先决条件

安装

测试服务器

⚙️ 配置

环境变量

MCP客户端配置

克劳德桌面

光标

其他MCP客户端

🛠️ 可用工具

openai_web_search

参数

支持的型号

💬 用法示例

快速搜索

本地化搜索

具体型号选择

常见用例

🤖 选型指南

标准Web搜索（默认）

快速网络搜索

高级搜索

📦 发展

📤 向NPM发布

先决条件

出版前

发布步骤

发布过程中会发生什么

发布后

发布更新

可选：范围包

验证发布

🏗️ 项目结构

🐛 调试与故障排除

使用MCP检查器

常见问题

“OPENAI_API_KEY环境变量是必需的”

“无效的OpenAI API密钥格式”

“服务器未出现在Claude Desktop中”

“找不到命令'bun'”

日志记录

测试单个组件

📄 许可证

🙏 致谢

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

代码索引分析工具

Flomo笔记服务

Unity编辑器AI集成插件

`openai_web_search`