openai-mcp-server

An MCP server that puts the OpenAI API into any MCP client — Claude Desktop, Claude Code, Cowork, Cursor, or anything else that speaks the protocol.

Nine tools: text generation, chat completions, model discovery, image generation and editing, transcription, speech synthesis, embeddings, and moderation.

Why this exists

There is no official OpenAI plugin in the Claude plugin catalogue. This server is the equivalent, built as a normal open-source project you own and can extend.

Related MCP server: OpenAI Assistant MCP Server

Tools

Every tool takes response_format: "markdown" | "json" — markdown for reading, JSON for processing. All tools also return structuredContent, so clients that understand output schemas get typed data without parsing.

Requirements

• Node.js 20 or newer

• An OpenAI API key with available quota

Install

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

Verify the build:

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

Configure your MCP client

The server speaks MCP over stdio, so the client launches it as a subprocess.

Claude Desktop

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

Restart Claude Desktop afterwards.

Claude Code

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

Any other MCP client

Point it at node /absolute/path/to/dist/index.js with OPENAI_API_KEY in the environment.

Configuration

Only OPENAI_API_KEY is required. See .env.example for a copyable template.

Model IDs change. OpenAI adds, renames and retires models, and access differs per project. Every default is overridable, and openai_list_models reports what your key can actually reach — if a call fails with "model not found", start there.

Security model

Two deliberate constraints:

The filesystem is sandboxed. Tools that read local files (openai_edit_image, openai_transcribe_audio) accept only absolute paths inside OPENAI_MCP_ALLOWED_DIRS. Paths are canonicalised with realpath before the check, so symlinks and ../ traversal cannot escape. The output directory is always allowed; nothing else is, until you add it. Keep that list narrow.

Binary output never enters the conversation. Images, audio and embedding vectors are written to disk and only their paths are returned. A single base64 PNG or a 3072-float vector would otherwise flood the model's context window.

The API key is read from the environment only — it never appears in a tool argument, a log line, or an error message.

Examples

Ask your MCP client in plain language; it picks the tool.

"Use the OpenAI server to summarise this text in three sentences."

→ openai_generate_text

"Which OpenAI embedding models can I use?"

→ openai_list_models with filter="embedding"

"Generate a transparent PNG logo of a blue fox."

→ openai_generate_image with background="transparent"

"Transcribe ~/Documents/audio/interview.m4a in German."

→ openai_transcribe_audio with language="de" — requires that directory in OPENAI_MCP_ALLOWED_DIRS

"Embed these 40 product descriptions so I can cluster them."

→ openai_create_embeddings, then read the JSON file it reports

Development

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/

The test suite covers configuration parsing, the filesystem sandbox (including symlink escape and traversal), error formatting and response shaping. It never contacts the OpenAI API.

Project layout

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

Adding a tool

1. Write a Zod schema with .strict() and a .describe() on every field.

2. Register it with server.registerTool(name, config, handler) — include title, description, inputSchema, outputSchema and annotations.

3. Return via toolResult(...) so markdown/JSON handling and the character limit stay consistent; catch errors with errorResult(...).

4. Add the registration call in src/index.ts and a test in test/.

Troubleshooting

The server logs to stderr; stdout carries the JSON-RPC stream and must stay clean.

License

MIT — see LICENSE.