内容
# OpenAI MCP 服务器
**完整的 OpenAI API 接口作为模型上下文协议工具，适用于 Claude Code、Cursor、Windsurf 和任何 MCP 客户端。**
[](https://www.npmjs.com/package/openai-mcp-server)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
单个标准输入/输出 MCP 服务器，暴露 **42 种工具**，涵盖所有主要的 OpenAI 端点：响应、聊天补全、图像（gpt-image-1.5）、音频（TTS + 转录 + 翻译）、嵌入、审核、文件、批次、向量存储、微调和多部分大上传。
## 功能
- **响应 API** （主要）：推理、内置工具（`web_search`、`file_search`、`code_interpreter`、`image_generation`）、后台模式、存储响应、输入项检索。
- **聊天补全**：带有自动路由的旧端点，在推理模型参数（`reasoning_effort`、`max_completion_tokens`）和标准参数之间。
- **图像**：`gpt-image-1.5` 生成 + 编辑带有遮罩，保存到磁盘，base64 流式传输，输入保真度。
- **音频**：`gpt-4o-mini-tts` 文本转语音，`gpt-4o-transcribe` + `whisper-1` 转录带有字/段时间戳，英语翻译。
- **嵌入**：`text-embedding-3-large` 满 3072 维度。
- **文件**：上传、列表、检索、下载、删除（需权限）。
- **批次**：50% 成本的异步作业，适用于响应/聊天/嵌入/审核/图像。
- **向量存储**：创建、列表、检索、附加文件（单个 + 批次）、搜索、删除。
- **微调**：创建作业、列表、检索、取消、事件、检查点。
- **大上传**：多部分流式上传至 **8 GB**，64 MB 块，带有 MD5 完整性。
- **最大能力默认值**：`reasoning_effort=high`、`verbosity=high`、图像质量高、1024x1536 肖像、每个模型自动填充 `max_output_tokens`。
- **内置安全**：路径拒绝列表、写入基准名拒绝、托管工具块（`mcp`/`shell`/`computer_use`）、破坏性操作门控、401 缓存失效、图像 URL 上的 SSRF 防护。
## 安装
### 从 npm
```bash
npm install -g openai-mcp-server
```
二进制文件 `openai-mcp-server` 被放置在您的 `PATH` 上。
### 从源码
```bash
git clone https://github.com/salviz/openai-mcp-server.git
cd openai-mcp-server
npm install
node index.js # 简单检查 — 它将等待来自 stdio 的 MCP 客户端
```
需要 **Node.js >= 20**。适用于 Linux、macOS、Windows（WSL）和 Android/Termux。
## API 密钥
服务器从三个来源解析您的 OpenAI API 密钥，按此顺序 — 第一个匹配项获胜：
### 1. 环境变量（最简单）
```bash
export OPENAI_API_KEY="sk-proj-..."
openai-mcp-server
```
### 2. 文件引用（适用于秘密管理器、1Password CLI、`pass`等）
```bash
echo -n "sk-proj-..." > ~/.config/openai/api_key
chmod 600 ~/.config/openai/api_key
export OPENAI_API_KEY_FILE="~/.config/openai/api_key"
openai-mcp-server
```
路径会被 `~` 展开。只读取第一行，修剪空白。
### 3. Google Cloud Secret Manager 备用
如果以上两者均未设置，并且 `gcloud` 可用，服务器将尝试：
```bash
gcloud secrets versions access latest \
--secret="$OPENAI_MCP_GCP_SECRET" \
--project="$OPENAI_MCP_GCP_PROJECT"
```
设置项目和密钥名称：
```bash
export OPENAI_MCP_GCP_PROJECT="my-gcp-project"
export OPENAI_MCP_GCP_SECRET="openai-api-key" # 默认如果未设置
export OPENAI_MCP_GCLOUD_BIN="/usr/bin/gcloud" # 如果非标准则覆盖
openai-mcp-server
```
gcloud 子进程运行环境被清理（无继承的 `PATH` 技巧）。
## 注册到 Claude Code
添加到 `~/.claude.json`（用户范围）或 `~/.claude/settings.json` 下的 `mcpServers`：
```json
{
"mcpServers": {
"openai": {
"command": "openai-mcp-server",
"env": {
"OPENAI_API_KEY": "sk-proj-..."
}
}
}
}
```
如果从源码安装，请指向绝对路径：
```json
{
"mcpServers": {
"openai": {
"command": "node",
"args": ["~/openai-mcp-server/index.js"],
"env": { "OPENAI_API_KEY": "sk-proj-..." }
}
}
}
```
重启 Claude Code。工具显示为 `mcp__openai__openai_responses` 等。
## 注册到 Cursor / Windsurf / 其他 MCP 客户端
### Cursor (`~/.cursor/mcp.json`)
```json
{
"mcpServers": {
"openai": {
"command": "openai-mcp-server",
"env": { "OPENAI_API_KEY": "sk-proj-..." }
}
}
}
```
### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
```json
{
"mcpServers": {
"openai": {
"command": "openai-mcp-server",
"env": { "OPENAI_API_KEY": "sk-proj-..." }
}
}
}
```
任何 MCP stdio 客户端都有效 — 服务器通过标准输入/输出使用标准 MCP 协议。
## 工具目录
### 响应（5）
| 工具 | 描述 |
|------|-------------|
| `openai_responses` | 主要端点 — 使用文本、图像、文件、推理努力和内置工具创建响应。默认阻止托管的 `mcp`/`shell`/`computer_use` 类型。自动填充每个模型系列的 `max_output_tokens`。 |
| `openai_response_get` | 通过 ID 检索存储的响应。 |
| `openai_response_cancel` | 取消后台响应。 |
| `openai_response_delete` | 删除存储的响应。需 `OPENAI_MCP_ALLOW_DESTRUCTIVE=1` 权限。 |
| `openai_response_input_items` | 列出存储的输入项。 |
### 聊天（1）
| 工具 | 描述 |
|------|-------------|
| `openai_chat` | 聊天补全端点。对于新模型和内置工具，请优先使用 `openai_responses`。 |
### 图像（2）
| 工具 | 描述 |
|------|-------------|
| `openai_image_generate` | 生成图像。默认 `gpt-image-1.5`，质量高，1024x1536。保存到本地路径或返回 base64。 |
| `openai_image_edit` | 编辑图像（可选遮罩）。基于 `gpt-image-1.5` 的引用编辑。 |
### 音频（3）
| 工具 | 描述 |
|------|-------------|
| `openai_tts` | 文本转语音。默认 `gpt-4o-mini-tts`，语音 `nova`，mp3。写入音频文件到 `save_to`。 |
| `openai_transcribe` | 语音转文本。默认 `gpt-4o-transcribe`（json）。使用 `whisper-1` 获取 `verbose_json` + 字/段时间戳。 |
| `openai_translate_audio` | 将音频翻译成英语（Whisper 翻译端点）。 |
### 文件（5）
| 工具 | 描述 |
|------|-------------|
| `openai_file_upload` | 上传本地文件（最多 500 MB）。返回用于响应/聊天/助手/批次的 `file_id`。 |
| `openai_file_list` | 列出上传的文件，可选按用途过滤。 |
| `openai_file_get` | 检索单个文件的元数据。 |
| `openai_file_delete` | 删除上传的文件。需 `OPENAI_MCP_ALLOW_DESTRUCTIVE=1` 权限。 |
| `openai_file_content` | 下载原始文件内容到本地路径。 |
### 批次（4）
| 工具 | 描述 |
|------|-------------|
| `openai_batch_create` | 创建批次作业（50% 成本，异步）。支持响应、聊天、补全、嵌入、审核、图像、视频端点。 |
| `openai_batch_retrieve` | 通过 ID 检索批次作业。 |
| `openai_batch_cancel` | 取消批次作业。 |
| `openai_batch_list` | 列出批次作业。 |
### 向量存储（9）
| 工具 | 描述 |
|------|-------------|
| `openai_vector_store_create` | 创建向量存储（用于 `file_search` 工具）。 |
| `openai_vector_store_list` | 列出向量存储。 |
| `openai_vector_store_retrieve` | 检索向量存储。 |
| `openai_vector_store_delete` | 删除向量存储。需 `OPENAI_MCP_ALLOW_DESTRUCTIVE=1` 权限。 |
| `openai_vector_store_file_add` | 附加上传的文件到向量存储。 |
| `openai_vector_store_file_list` | 列出附加到向量存储的文件。 |
| `openai_vector_store_file_remove` | 移除文件。需 `OPENAI_MCP_ALLOW_DESTRUCTIVE=1` 权限。 |
| `openai_vector_store_file_batch_create` | 批量附加多个文件到一个批次中。 |
| `openai_vector_store_search` | 通过查询搜索向量存储。 |
### 微调（6）
| 工具 | 描述 |
|------|-------------|
| `openai_fine_tune_create` | 从上传的 JSONL 训练文件创建微调作业。 |
| `openai_fine_tune_retrieve` | 检索微调作业。 |
| `openai_fine_tune_list` | 列出微调作业。 |
| `openai_fine_tune_cancel` | 取消微调作业。 |
| `openai_fine_tune_events` | 列出作业的事件（进度流）。 |
| `openai_fine_tune_list_checkpoints` | 列出中间检查点模型 ID。 |
### 大上传（2）
| 工具 | 描述 |
|------|-------------|
| `openai_upload_large_file` | 多部分上传最多 8 GB。流式传输 64 MB 部分，带有增量 MD5。 |
| `openai_upload_cancel` | 取消正在进行的上传。 |
### 嵌入、审核、模型、健康检查（5）
| 工具 | 描述 |
|------|-------------|
| `openai_embed` | 创建嵌入。默认 `text-embedding-3-large`，3072 维度。 |
| `openai_moderation` | 通过 `omni-moderation-latest`（多模态）运行审核检查。 |
| `openai_list_models` | 列出账户上的所有模型（动态、始终当前）。 |
| `openai_model_retrieve` | 检索单个模型的元数据。 |
| `openai_ping` | 健康检查 — 加载密钥并返回红名 + 可见性探测。 |
**共 42 种工具。## 环境变量
| 变量 | 用途 | 默认值 |
|----------|---------|---------|
| `OPENAI_API_KEY` | 主要 API 密钥来源。 | — |
| `OPENAI_API_KEY_FILE` | 从文件路径读取密钥（`~` 展开）。 | — |
| `OPENAI_ORG_ID` | OpenAI 客户端的组织 ID。 | — |
| `OPENAI_PROJECT_ID` | OpenAI 客户端的项目 ID。 | — |
| `OPENAI_BASE_URL` | 覆盖 API 基本 URL（代理、Azure 兼容网关）。 | `https://api.openai.com/v1` |
| `OPENAI_MCP_GCP_PROJECT` | GCP 项目的 Secret Manager 备用。 | — |
| `OPENAI_MCP_GCP_SECRET` | Secret Manager 备用的密钥名称。 | `openai-api-key` |
| `OPENAI_MCP_GCLOUD_BIN` | `gcloud` 二进制文件的绝对路径。 | — |
| `OPENAI_MCP_ALLOW_PATHS` | 允许路径的冒号分隔路径列表。 | — |
| `OPENAI_MCP_DENY_PATHS` | 额外的冒号分隔路径拒绝列表。 | — |
| `OPENAI_MCP_MAX_FILE_BYTES` | 内联文件读取的最大字节数（图像、附件）。 | `52428800`（50 MB） |
| `OPENAI_MCP_MAX_AUDIO_BYTES` | 音频转录上传的最大字节数。 | `209715200`（200 MB） |
| `OPENAI_MCP_ALLOW_HOSTED_TOOLS` | 允许托管工具类型的标志。 | `0` |
| `OPENAI_MCP_ALLOW_DESTRUCTIVE` | 允许删除工具的标志。 | `0` |
| `OPENAI_MCP_TIMEOUT_MS` | OpenAI SDK 的每个请求超时时间。 | `600000`（10 分钟） |
## 安全模型
该服务器设计为与 LLM 安全连接，LLM 可以代表您发出任意工具调用。
### 路径拒绝列表
所有读取或写入本地路径的工具（`image_paths`、`file_path`、`save_to`等）都通过一个解析器，该解析器：
- 展开 `~` 到用户当前目录。
- 调用 `realpathSync` 以防止符号链接逃逸。
- 默认阻止以下内容（针对注入式 LLM 攻击，防止秘密外泄）：
- `~/.ssh`、`~/.gnupg`、`~/.aws`、`~/.config/gcloud`、`~/.docker`、`~/.kube`
- `~/.claude`、`~/.claude.json`
- `~/.bash_history`、`~/.zsh_history`、`~/.netrc`、`~/.npmrc`、`~/.pypirc`、`~/.git-credentials`
- `/etc/shadow`、`/etc/gshadow`、`/proc`
- 您通过 `OPENAI_MCP_DENY_PATHS` 添加的任意路径
- 允许列表是累加的：`OPENAI_MCP_ALLOW_PATHS` 下的任何内容都是允许的，即使它被拒绝。
### 写入基准名拒绝
即使在拒绝列表之外，也会阻止写入这些 shell-init/auth 基础名称：
```
.bashrc .bash_profile .bash_login .profile .zshrc .zprofile .zlogin
.zshenv .kshrc .cshrc .tcshrc .inputrc .termux.properties
authorized_keys known_hosts .vimrc .viminfo .config
```
这可以防止 LLM 用注入的提示覆盖您的 shell rc 文件，无论文件在文件系统中的哪个位置。
### 托管工具块
响应 API 允许您传递托管工具类型，如 `mcp`、`shell` 和 `computer_use`。这些允许远程基础设施（OpenAI 的沙箱或第三方 MCP 端点）执行操作。我们默认阻止这些：
- `mcp` — 允许注入式 LLM 在调用期间注册恶意 MCP 服务器。
- `shell` — 任意远程 shell 执行。
- `computer_use` — 屏幕控制。
设置 `OPENAI_MCP_ALLOW_HOSTED_TOOLS=1` 仅当您明确信任工具有效载荷源时。
### 破坏性操作门控
删除工具（`openai_file_delete`、`openai_response_delete`、`openai_vector_store_delete`、`openai_vector_store_file_remove`）被禁用，除非 `OPENAI_MCP_ALLOW_DESTRUCTIVE=1`。这可以防止注入式提示，例如“请清理您的文件”，从而删除您的整个数据集、缓存的响应或向量存储库。
### 401 缓存失效
OpenAI 客户端在调用之间缓存以提高速度。任何 HTTP 401 错误时，都会使缓存的客户端失效，以便旋转的密钥立即生效，无需重启服务器。
### SSRF 防护
`image_urls` 在转发之前会进行验证：
- 仅限 `http:` / `https:` 方案。
- 拒绝 `localhost`、`127.0.0.1`、`0.0.0.0`、`::1`、`metadata.google.internal`。
- 拒绝 RFC1918 (`10.x`、`192.168.x`、`172.16.x`-`172.31.x`)、链路本地 (`169.254.x`、`fe80::`) 和唯一本地 (`fc00::/7`) 地址。
防止 LLM 代表您诱骗服务器获取云元数据或内部网络。
## 默认值
| 控件 | 默认值 |
|------|---------|
| 文本模型 | `gpt-5.4` |
| `reasoning_effort` | `high` |
| `verbosity` | `high` |
| `reasoning_summary` | `auto` |
| 图像模型 | `gpt-image-1.5` |
| 图像大小 | `1024x1536` |
| 图像质量 | `high` |
| TTS 模型 | `gpt-4o-mini-tts` |
| TTS 语音 | `nova` |
| 转录模型 | `gpt-4o-transcribe` |
| 嵌入模型 | `text-embedding-3-large` @ 3072 维度 |
| 审核模型 | `omni-moderation-latest` |
| 每个请求的超时时间 | 10 分钟 |
| 每个模型的 `max_output_tokens` | `gpt-5.*` 128K，`o-series` 100K，`gpt-4.1*` 32K，`gpt-4o*` 16K，`gpt-4*` 8K |
模型可用性因帐户和日期而异。在连接默认设置之前，请运行 `openai_list_models` 以查看您的密钥实际可访问的内容。
## 示例
所有示例都显示了 LLM 传递给工具的 JSON `input`。
### 1. 快速推理调用
```json
{
"tool": "openai_responses",
"input": {
"input": "向三年级工程师解释 CAP 定理，三段。",
"reasoning_effort": "high"
}
}
```
### 2. 分析本地 PDF
```json
{
"tool": "openai_responses",
"input": {
"input": "总结关键发现并列出使用的所有统计测试。",
"file_paths": ["~/papers/clinical-trial.pdf"],
"reasoning_effort": "high",
"verbosity": "high"
}
}
```
### 3. 生成图像到磁盘
```json
{
"tool": "openai_image_generate",
"input": {
"prompt": "黎明时分的灯塔的极简主义水彩插图。",
"size": "1024x1536",
"quality": "high",
"save_to": "~/images/lighthouse.png"
}
}
```
### 4. 后台推理 + 轮询
启动长时间作业：
```json
{
"tool": "openai_responses",
"input": {
"input": "为多区域 Kafka 部署生成 20 页的技术设计文档。",
"reasoning_effort": "high",
"background": true,
"store": true
}
}
```
然后轮询：
```json
{
"tool": "openai_response_get",
"input": { "response_id": "resp_abc123", "response_format": "text" }
}
```
### 5. 上传大型数据集并微调
```json
{
"tool": "openai_upload_large_file",
"input": {
"path": "~/datasets/corpus.jsonl",
"purpose": "fine-tune"
}
}
```
```json
{
"tool": "openai_fine_tune_create",
"input": {
"model": "gpt-4.1-nano",
"training_file": "file-xyz789",
"suffix": "my-domain-v1",
"method": { "type": "supervised" }
}
}
```
### 6. 嵌入一批文档
```json
{
"tool": "openai_embed",
"input": {
"input": ["第一个文档", "第二个文档", "第三个文档"],
"dimensions": 3072,
"include_vectors": false
}
}
```
## 故障排除
### “未找到 OpenAI API 密钥”
三个解析路径均未返回密钥。请使用以下命令验证：
```bash
echo "$OPENAI_API_KEY" | head -c 10
ls -la "$OPENAI_API_KEY_FILE"
gcloud secrets versions access latest --secret="$OPENAI_MCP_GCP_SECRET" --project="$OPENAI_MCP_GCP_PROJECT"
```
### “路径在拒绝列表中”
您尝试读取或写入受保护的位置。移动文件或允许其父目录：
```bash
export OPENAI_MCP_ALLOW_PATHS="/home/me/workdir:/tmp/safe"
```
### “托管工具类型 … 默认情况下禁用”
您传递了 `tools: [{type: "mcp"}]`（或 `shell` / `computer_use`）。设置 `OPENAI_MCP_ALLOW_HOSTED_TOOLS=1` 仅当您信任有效载荷。
### “破坏性操作已禁用”
设置 `OPENAI_MCP_ALLOW_DESTRUCTIVE=1` 以启用删除工具。
### “文件是 N 个字节；超过 … 限制”
提高 `OPENAI_MCP_MAX_FILE_BYTES`（内联附件）或 `OPENAI_MCP_MAX_AUDIO_BYTES`（转录），或使用 `openai_upload_large_file` 处理最多 8 GB 的文件。
### `openai_responses` 输出中的 `status=failed`
模型返回错误状态。工具响应标记为 `isError: true`。切换到 `response_format: "json"` 以查看完整的错误负载，或使用 ID 调用 `openai_response_get`。
### 每个调用的 HTTP 401 错误
您的密钥无效或已轮换。服务器将在下一次调用时重新加载 — 您不需要重启它。
### 推理模型忽略 `max_tokens`
推理模型 (`gpt-5.*`、`o*`) 使用 `max_completion_tokens`，而不是 `max_tokens`。服务器根据模型 ID 自动路由此问题。
## 贡献
欢迎提交拉取请求。
1. 在 GitHub 上分叉仓库。
2. 创建一个分支：`git checkout -b fix/my-issue`。
3. 检查您触摸的每个文件：`node --check tools/your_file.js`。
4. 在推送之前，请通过 MCP 客户端手动进行烟雾测试。
5. 打开一个 PR 到 `main`，附上对更改内容的描述和原因。
添加工具时，请遵循 `tools/*.js` 中的现有模式：
- 通过 `server.tool(name, description, zodSchema, handler)` 注册。
- 通过 `validateTools` / `validateInputMessages` 验证任何 `tools` / `messages` 数组，以强制实施托管工具块。
- 通过 `resolvePath(path, { forWrite: true })` 路由写入。
- 从 `client.js` 使用 `ok`、`fail`、`asJson` 以获得一致的响应格式。
## 许可证
MIT。参见 `LICENSE`。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器