openai-mcp-server

一个 MCP 服务器，将 OpenAI API 接入任何 MCP 客户端——Claude Desktop、Claude Code、Cowork、Cursor，或任何其他支持该协议的工具。

九个工具：文本生成、聊天补全、模型发现、图像生成与编辑、转写、语音合成、嵌入和内容审核。

为什么会有这个项目

Claude 插件目录中没有官方的 OpenAI 插件。这个服务器就是它的对应替代品，作为一个普通的开源项目，你可以掌握并扩展它。

Related MCP server: OpenAI Assistant MCP Server

工具

每个工具都接受 response_format: "markdown" | "json" ——markdown 用于阅读，json 用于处理。所有工具还会返回 structuredContent，因此理解输出 schema 的客户端无需解析即可获得结构化数据。

环境要求

• Node.js 20 或更高版本

• 具有可用余额的 OpenAI API 密钥

安装

git clone <your-repo-url> openai-mcp-server
cd openai-mcp-server
npm install
npm run build

验证构建：

node dist/index.js --version   # prints 1.0.0
node dist/index.js --help      # lists all environment variables

配置你的 MCP 客户端

服务器通过 stdio 使用 MCP 协议，因此客户端会将其作为子进程启动。

Claude Desktop

编辑 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openai": {
      "command": "node",
      "args": ["/absolute/path/to/openai-mcp-server/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-...",
        "OPENAI_MCP_OUTPUT_DIR": "/Users/you/openai-mcp-output"
      }
    }
  }
}

之后请重启 Claude Desktop。

Claude Code

claude mcp add openai \
  --env OPENAI_API_KEY=sk-proj-... \
  -- node /absolute/path/to/openai-mcp-server/dist/index.js

任何其他 MCP 客户端

将客户端指向 node /absolute/path/to/dist/index.js，并在环境中设置 OPENAI_API_KEY。

配置

只有 OPENAI_API_KEY 是必需的。可复制的模板见 .env.example。

模型 ID 会变。 OpenAI 会添加、重命名和停用模型，不同项目的访问权限也不同。所有默认值都可覆盖，而且 openai_list_models 会报告你的密钥实际可以访问的模型——如果某个调用报错“model not found”，先从那里查起。

安全模型

两个刻意设计的约束：

文件系统是沙箱化的。 读取本地文件的工具（openai_edit_image、openai_transcribe_audio）只接受位于 OPENAI_MCP_ALLOWED_DIRS 内的绝对路径。路径在检查前会通过 realpath 进行规范化，因此符号链接和 ../ 路径遍历都无法逃逸。输出目录始终允许访问；其他目录只有在你主动添加后才允许。请尽量保持该列表精简。

二进制输出绝不进入对话。 图像、音频和嵌入向量会写入磁盘，只返回路径。否则单个 base64 PNG 或 3072 维向量会淹没模型的上下文窗口。

API 密钥只从环境变量读取——它永远不会出现在工具参数、日志行或错误消息中。

示例

用自然语言向 MCP 客户端提问，它会选择合适的工具。

“使用 OpenAI 服务器将这个文本总结成三句话。”

→ openai_generate_text

“我可以使用哪些 OpenAI 嵌入模型？”

→ openai_list_models 并使用 filter="embedding"

“生成一只蓝色狐狸的透明 PNG 标志。”

→ openai_generate_image 并使用 background="transparent"

“用德语转写 ~/Documents/audio/interview.m4a。”

→ openai_transcribe_audio 并使用 language="de" ——这要求该目录位于 OPENAI_MCP_ALLOWED_DIRS 中

“将这些 40 条产品描述进行嵌入，以便我对它们进行聚类。”

→ openai_create_embeddings，然后读取它报告的 JSON 文件

开发

npm run dev        # watch mode via tsx
npm run typecheck  # tsc --noEmit, strict
npm test           # unit tests, no network calls
npm run build      # compile to dist/

测试套件涵盖配置解析、文件系统沙箱（包括符号链接逃逸和路径穿越）、错误格式化和响应整形。它不会访问 OpenAI API。

项目结构

src/
├── index.ts          entry point, server assembly, CLI flags
├── config.ts         environment parsing and validation
├── client.ts         OpenAI client construction
├── constants.ts      defaults, limits, response formats
├── errors.ts         API errors → actionable agent messages
├── files.ts          sandboxed read/write
├── format.ts         tool result shaping, character limit
└── tools/
    ├── text.ts       generate_text, chat_completion
    ├── models.ts     list_models
    ├── images.ts     generate_image, edit_image
    ├── audio.ts      transcribe_audio, text_to_speech
    └── analysis.ts   create_embeddings, moderate_content

添加工具

1. 编写带 .strict() 的 Zod schema，并为每个字段添加 .describe()。

2. 通过 registerTool(name, config, handler) 注册工具，包括 title、description、inputSchema、outputSchema 和 annotations。

3. 使用 toolResult(...) 返回，以保证 Markdown/JSON 处理及字符限制的一致性；用 errorResult(...) 捕获错误。

4. 在 src/index.ts 中添加注册调用，并在 test/ 中编写测试。

故障排查

服务器将日志输出到 stderr；stdout 承载 JSON-RPC 流，必须保持干净。

许可证

MIT —— 参见 LICENSE。