Skip to main content
Glama

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

Tool

What it does

Read-only

openai_generate_text

Generate text via the Responses API — instructions, reasoning effort, forced JSON, response chaining

no

openai_chat_completion

Send an explicit message history via Chat Completions

no

openai_list_models

List the model IDs your key can use, filtered and paginated

yes

openai_generate_image

Create images from a prompt, written to disk

no

openai_edit_image

Edit or combine existing images, optionally with a mask

no

openai_transcribe_audio

Transcribe a local audio file

no

openai_text_to_speech

Synthesize speech to an audio file

no

openai_create_embeddings

Embed texts for semantic search, written to JSON

no

openai_moderate_content

Check text against OpenAI's moderation policy

yes

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.

Install

As a Claude Desktop extension (easiest)

Download openai-mcp-server-<version>.mcpb from the releases page, double-click it, and paste your API key into the field Claude Desktop shows. Nothing else to install — the bundle carries its dependencies and runs on Claude Desktop's own Node runtime, so the machine needs no Node, no toolchain and no hand-edited config file.

The same dialog also offers the output folder, the folders the server may read from, a default text model and an alternative API base URL. All of them are optional.

To build the bundle yourself:

npm install
npm run pack:mcpb     # writes build/openai-mcp-server-<version>.mcpb

From source

For Claude Code, Cursor or any other MCP client:

git clone https://github.com/piorkowskim79/openai-mcp-server.git
cd openai-mcp-server
npm install
npm run build

Requires Node.js 20 or newer and an OpenAI API key with available quota.

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

Skip this section if you installed the .mcpb extension — Claude Desktop wires it up for you.

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.

Variable

Default

Purpose

OPENAI_API_KEY

—

Required. Your OpenAI API key

OPENAI_BASE_URL

OpenAI's default

Alternative endpoint (Azure, gateway, proxy)

OPENAI_ORG_ID

—

Organization ID

OPENAI_PROJECT_ID

—

Project ID

OPENAI_MCP_OUTPUT_DIR

<tmp>/openai-mcp

Where generated files are written

OPENAI_MCP_ALLOWED_DIRS

output dir only

Colon-separated absolute dirs the server may read from

OPENAI_MCP_TIMEOUT_MS

120000

Per-request timeout

OPENAI_MCP_MAX_RETRIES

2

Retries for transient failures

OPENAI_DEFAULT_TEXT_MODEL

gpt-5.6-terra

Default text model

OPENAI_DEFAULT_IMAGE_MODEL

gpt-image-2

Default image model

OPENAI_DEFAULT_EMBEDDING_MODEL

text-embedding-3-small

Default embedding model

OPENAI_DEFAULT_TRANSCRIPTION_MODEL

gpt-transcribe

Default transcription model

OPENAI_DEFAULT_SPEECH_MODEL

gpt-4o-mini-tts

Default speech model

OPENAI_DEFAULT_MODERATION_MODEL

omni-moderation-latest

Default moderation model

Any positional argument is also treated as a readable directory and merged into OPENAI_MCP_ALLOWED_DIRS:

node dist/index.js /Users/you/Documents/audio /Users/you/Pictures

This exists because a bundle manifest expands a multi-value directory setting into several argv entries; a single colon-separated environment variable cannot express that list unambiguously. Arguments must be absolute paths.

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/
npm run pack:mcpb  # build the Claude Desktop extension bundle

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

manifest.json         Claude Desktop extension manifest (tools, user config)
scripts/
└── pack-mcpb.sh      builds the .mcpb bundle
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

Symptom

Cause

Client shows no tools

Wrong path in the config, or the project was not built (npm run build)

Configuration error: OPENAI_API_KEY is not set (exit 78)

The key is missing from the client's env block

Error: Access to ... is not permitted

The path is outside OPENAI_MCP_ALLOWED_DIRS

Error: Not found on a generation

The model ID does not exist for your key — run openai_list_models

Error: Rate limit or quota exceeded

Retry later, or check billing on the project

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

License

MIT — see LICENSE.

Available Tools

9 tools
openai_chat_completionRun an OpenAI chat completionA

Send an explicit list of chat messages to an OpenAI model through the Chat Completions API.

Use this when you already hold a structured conversation history (system/user/assistant turns) and want it sent verbatim. For new single-prompt generations prefer openai_generate_text.

Args:

  • messages (array, required): [{ role: 'system'|'user'|'assistant'|'developer', content: string }], 1-200 entries

  • model (string): model ID, defaults to OPENAI_DEFAULT_TEXT_MODEL

  • max_completion_tokens (number): 1-200000

  • temperature (number): 0-2

  • top_p (number): 0-1

  • stop (string[]): up to 4 stop sequences

  • response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "id": string, // completion ID "model": string, // model that served the request "finish_reason": string | null, // "stop", "length", "content_filter", ... "content": string, // assistant reply text "refusal": string | null, // set when the model declined "usage": { "input_tokens": number|null, "output_tokens": number|null, "total_tokens": number|null } }

Examples:

  • Use when: replaying a saved conversation with a new final user turn

  • Use when: you need a stop sequence to cut generation at a delimiter

  • Don't use when: chaining stored responses (use openai_generate_text with previous_response_id)

Error Handling:

  • "Error: OpenAI rejected the request as invalid" often means an unsupported parameter for that model, e.g. temperature on a reasoning-only model

Inputs: messages (required), stop, model, top_p, +3 more. Returns: id, model, usage, content, +2 more

openai_create_embeddingsCreate embeddings with OpenAIA
Idempotent

Turn texts into embedding vectors for semantic search, clustering or deduplication.

By default the vectors are written to a JSON file and only the path plus metadata are returned, because a single vector holds up to 3072 floats. Set return_vectors=true for small batches when the numbers are needed directly.

Args:

  • texts (string[], required): 1-2048 texts to embed

  • model (string): embedding model ID, defaults to OPENAI_DEFAULT_EMBEDDING_MODEL

  • dimensions (number): shorten vectors (text-embedding-3 models only)

  • return_vectors (boolean): inline the vectors, max 5 texts (default false)

  • output_path (string): absolute path of the JSON file to write

  • response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "count": number, // number of vectors produced "dimensions": number, // length of each vector "file_path": string | null, // where the vectors were written "usage": { "input_tokens": number|null, "total_tokens": number|null }, "vectors": number[][] // present only when return_vectors is true }

The written JSON file has the shape: { "model": "text-embedding-3-small", "created_at": "2026-08-23T14:05:00.000Z", "count": 2, "dimensions": 1536, "items": [ { "index": 0, "text_preview": "…", "embedding": [0.0123, -0.0456] } ] }

Examples:

  • Use when: building a semantic index over documents -> texts=[...], then read the JSON file

  • Use when: comparing two sentences directly -> texts=[a, b], return_vectors=true

  • Don't use when: you just want a summary or classification (use openai_generate_text)

Error Handling:

  • "Error: return_vectors is only allowed for up to 5 texts" — lower the batch or read the file

  • "Error: OpenAI rejected the request as invalid" often means the model does not support the dimensions parameter

Inputs: texts (required), model, dimensions, output_path, +2 more. Returns: count, model, usage, vectors, +2 more

openai_edit_imageEdit an image with OpenAIA

Edit or extend existing images according to a text instruction, optionally restricted to a masked region.

Source images are read from disk (only from directories listed in OPENAI_MCP_ALLOWED_DIRS) and results are written back to disk.

Args:

  • prompt (string, required): the edit to apply

  • image_paths (string[], required): 1-4 absolute paths to source images

  • mask_path (string): absolute path to a PNG mask; transparent pixels mark the area to replace

  • model (string): image model ID, defaults to OPENAI_DEFAULT_IMAGE_MODEL

  • n (number): 1-4 variants (default 1)

  • size ('auto'|'1024x1024'|'1536x1024'|'1024x1536'|'512x512'|'256x256'): default 'auto'

  • output_dir (string): absolute target directory

  • response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "count": number, "images": [ { "index": number, "path": string, "bytes": number } ], "revised_prompt": string | null }

Examples:

  • Use when: "Replace the sky in photo.png with a sunset" -> image_paths=["/data/photo.png"], prompt="sunset sky"

  • Use when: combining several product shots into one scene -> image_paths=[...]

  • Don't use when: creating an image from scratch (use openai_generate_image)

Error Handling:

  • "Error: File not found" means the path does not exist

  • "Error: Access to ... is not permitted" means the file lives outside OPENAI_MCP_ALLOWED_DIRS

Inputs: prompt (required), image_paths (required), n, size, +4 more. Returns: count, model, images, revised_prompt

openai_generate_imageGenerate an image with OpenAIA

Create one or more images from a text prompt and write them to disk.

Images are never returned inline — the tool saves each file and reports its absolute path, so the agent's context stays small.

Args:

  • prompt (string, required): what the image should show

  • model (string): image model ID, defaults to OPENAI_DEFAULT_IMAGE_MODEL

  • n (number): 1-4 images (default 1)

  • size ('auto'|'1024x1024'|'1536x1024'|'1024x1536'|'512x512'|'256x256'): default 'auto'

  • quality ('auto'|'low'|'medium'|'high'): default 'auto'

  • background ('auto'|'transparent'|'opaque'): default 'auto'; 'transparent' needs png or webp

  • output_format ('png'|'jpeg'|'webp'): default 'png'

  • output_dir (string): absolute target directory, defaults to OPENAI_MCP_OUTPUT_DIR

  • response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "count": number, "images": [ { "index": number, "path": string, "bytes": number } ], "revised_prompt": string | null // prompt rewrite the model applied, when reported }

Examples:

  • Use when: "Draw a logo of a blue fox" -> prompt="minimalist blue fox logo, flat vector"

  • Use when: you need a transparent sticker -> background="transparent", output_format="png"

  • Don't use when: you want to modify an existing picture (use openai_edit_image)

Error Handling:

  • "Error: Access to ... is not permitted" means output_dir is outside OPENAI_MCP_ALLOWED_DIRS

  • "Error: OpenAI rejected the request as invalid" often means size or quality is unsupported by that model

Inputs: prompt (required), n, size, model, +5 more. Returns: count, model, images, revised_prompt

openai_generate_textGenerate text with OpenAIA

Generate text with an OpenAI model through the Responses API — OpenAI's current interface for single-turn and chained generation.

Use this as the default text tool. It supports plain prompting, system instructions, reasoning effort control, forced JSON output and multi-turn chaining via previous_response_id.

Args:

  • input (string, required): the prompt

  • model (string): model ID, defaults to OPENAI_DEFAULT_TEXT_MODEL

  • instructions (string): system-level steering

  • max_output_tokens (number): 1-200000

  • temperature (number): 0-2

  • top_p (number): 0-1

  • reasoning_effort ('minimal'|'low'|'medium'|'high'): effort for reasoning models

  • json_object (boolean): force a valid JSON object as output (default false)

  • previous_response_id (string): continue an earlier stored response

  • store (boolean): persist the response for later chaining (default false)

  • response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "id": string, // response ID, usable as previous_response_id when store=true "model": string, // model that actually served the request "status": string | null, // e.g. "completed" or "incomplete" "output_text": string, // the generated text "usage": { "input_tokens": number|null, "output_tokens": number|null, "total_tokens": number|null } }

Examples:

  • Use when: "Summarise this contract clause" -> input=, instructions="Answer in German, max 3 sentences"

  • Use when: "Give me the result as JSON" -> json_object=true

  • Use when: continuing a stored conversation -> previous_response_id="resp_..."

  • Don't use when: you need to send an existing multi-message history verbatim (use openai_chat_completion)

Error Handling:

  • "Error: Not found" means the model ID does not exist for this key — call openai_list_models

  • "Error: Rate limit or quota exceeded" means retry later or lower the request rate

Inputs: input (required), model, store, top_p, +7 more. Returns: id, model, usage, status, +1 more

openai_list_modelsList available OpenAI modelsA
Read-onlyIdempotent

List the model IDs the configured API key has access to, optionally filtered by substring.

Call this before guessing a model ID — OpenAI adds, renames and retires models regularly, and access differs per project. The response also reports the model IDs this server uses by default for each capability.

Args:

  • filter (string): case-insensitive substring match on the model ID, e.g. "embedding"

  • limit (number): 1-200 (default 50)

  • offset (number): pagination offset (default 0)

  • response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "total": number, // number of models matching the filter "count": number, // models in this response "offset": number, // current pagination offset "models": [ { "id": string, "owned_by": string, "created_at": string } // created_at is ISO 8601 UTC ], "has_more": boolean, "next_offset": number, // present only when has_more is true "defaults": { "text": string, "image": string, "embedding": string, "transcription": string, "speech": string, "moderation": string } }

Examples:

  • Use when: "Which embedding models can I use?" -> filter="embedding"

  • Use when: a generation failed with "model not found" -> call without filter and inspect the list

  • Don't use when: you only need the server's configured defaults for a single call — those are applied automatically

Error Handling:

  • "Error: Authentication failed" means OPENAI_API_KEY is invalid

  • An empty list with a filter set means no model ID contains that substring

Inputs: limit, filter, offset, response_format. Returns: count, total, models, offset, +3 more

openai_moderate_contentModerate content with OpenAIA
Read-onlyIdempotent

Check text against OpenAI's moderation policy and report which categories it triggers.

Use this before publishing or forwarding user-supplied text, or to explain why a generation was refused.

Args:

  • input (string, required): the text to check

  • model (string): moderation model ID, defaults to OPENAI_DEFAULT_MODERATION_MODEL

  • response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "flagged": boolean, // true when any category was triggered "flagged_categories": string[], // e.g. ["violence", "harassment/threatening"] "scores": { "": number } // confidence per category, 0.0-1.0 }

Examples:

  • Use when: "Is this user comment acceptable?" -> input=

  • Use when: auditing a batch of support messages before archiving them

  • Don't use when: you need a stylistic or factual review (use openai_generate_text)

Error Handling:

  • "Error: Not found" means the moderation model ID is wrong — call openai_list_models with filter="moderation"

Inputs: input (required), model, response_format. Returns: model, scores, flagged, flagged_categories

openai_text_to_speechSynthesize speech with OpenAIA

Turn text into spoken audio and write the result to disk.

The audio is never returned inline — the tool reports the absolute path of the generated file.

Args:

  • input (string, required): the text to speak, up to 10,000 characters

  • voice (string): voice name, default "alloy"

  • model (string): speech model ID, defaults to OPENAI_DEFAULT_SPEECH_MODEL

  • instructions (string): delivery guidance such as "speak slowly and warmly"

  • format ('mp3'|'opus'|'aac'|'flac'|'wav'|'pcm'): default 'mp3'

  • speed (number): 0.25-4.0, default 1

  • output_path (string): absolute target file, defaults to a timestamped file in OPENAI_MCP_OUTPUT_DIR

  • response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "voice": string, "path": string, // absolute path of the written audio file "bytes": number, // file size "format": string // container that was written }

Examples:

  • Use when: "Read this paragraph aloud as an mp3" -> input=

  • Use when: you need a slower narration -> speed=0.85

  • Don't use when: you want a transcript of existing audio (use openai_transcribe_audio)

Error Handling:

  • "Error: Access to ... is not permitted" means output_path is outside OPENAI_MCP_ALLOWED_DIRS

  • "Error: OpenAI rejected the request as invalid" often means the voice name is unknown to that model

Inputs: input (required), model, speed, voice, +4 more. Returns: path, bytes, model, voice, +1 more

openai_transcribe_audioTranscribe audio with OpenAIA
Idempotent

Transcribe a local audio file to text.

The file is read from disk (only from directories listed in OPENAI_MCP_ALLOWED_DIRS) and uploaded to OpenAI. Supported containers include mp3, mp4, m4a, wav, webm, flac and ogg; the API limit is 25 MB per file.

Args:

  • file_path (string, required): absolute path to the audio file

  • model (string): transcription model ID, defaults to OPENAI_DEFAULT_TRANSCRIPTION_MODEL

  • language (string): ISO-639-1 code such as "de" or "en"

  • prompt (string): vocabulary hint for names and jargon

  • response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "text": string, // full transcript "language": string | null, // detected or supplied language "duration_seconds": number | null, // audio length when reported "source_file": string // canonical path that was read }

Examples:

  • Use when: "What was said in this voice memo?" -> file_path="/data/memo.m4a"

  • Use when: transcribing a German interview -> language="de"

  • Don't use when: the file is a video you only want summarised — extract the audio track first

Error Handling:

  • "Error: File not found" means the path does not exist

  • "Error: Payload too large" means the file exceeds 25 MB — split it before retrying

Inputs: file_path (required), model, prompt, language, +1 more. Returns: text, model, language, source_file, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool maps to a distinct OpenAI capability (text, chat history, images, audio, embeddings, moderation, model discovery). openai_generate_text and openai_chat_completion are the only potentially confusable pair, but their descriptions clearly separate single-prompt/chaining from explicit message histories.

    Naming Consistency4/5

    All tools share an openai_ prefix and snake_case, with mostly verb_noun names like generate_text, edit_image, list_models. openai_chat_completion and openai_text_to_speech break the verb_noun pattern slightly because they mirror API endpoint names, but the convention remains predictable.

    Tool Count5/5

    9 tools is appropriate for an OpenAI API surface: one tool per major modality (text, image, audio, embeddings, moderation) plus model discovery. No tool feels redundant or missing at the count level.

    Completeness4/5

    The set covers text generation, chat completions, image generation/editing, transcription, speech synthesis, embeddings, and moderation, which are the core OpenAI workflows. Minor gaps exist—notably no vision/analysis of image inputs and no fine-tuning/batch management—but agents can accomplish typical tasks without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      C
      quality
      Not graded
      maintenance
      Enables interaction with OpenAI-compatible APIs (like Ollama) through MCP tools. Provides access to chat completions, model listings, and embeddings generation from local or remote OpenAI-style endpoints.
      3
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server exposing the OpenAI platform REST API as tools for file management, fine-tuning, inference, images, audio, batch processing, and organization usage/costs.
      -