openai-mcp-server
Provides tools for interacting with OpenAI's API, enabling text generation, chat completions, model discovery, image generation and editing, audio transcription, speech synthesis, embeddings, and content moderation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openai-mcp-server List the models my API key can access."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Generate text via the Responses API — instructions, reasoning effort, forced JSON, response chaining | no |
| Send an explicit message history via Chat Completions | no |
| List the model IDs your key can use, filtered and paginated | yes |
| Create images from a prompt, written to disk | no |
| Edit or combine existing images, optionally with a mask | no |
| Transcribe a local audio file | no |
| Synthesize speech to an audio file | no |
| Embed texts for semantic search, written to JSON | no |
| 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>.mcpbFrom 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 buildRequires 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 variablesConfigure 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.jsonWindows:
%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.jsAny 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 |
| — | Required. Your OpenAI API key |
| OpenAI's default | Alternative endpoint (Azure, gateway, proxy) |
| — | Organization ID |
| — | Project ID |
|
| Where generated files are written |
| output dir only | Colon-separated absolute dirs the server may read from |
|
| Per-request timeout |
|
| Retries for transient failures |
|
| Default text model |
|
| Default image model |
|
| Default embedding model |
|
| Default transcription model |
|
| Default speech model |
|
| 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/PicturesThis 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 bundleThe 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_contentAdding a tool
Write a Zod schema with
.strict()and a.describe()on every field.Register it with
server.registerTool(name, config, handler)— includetitle,description,inputSchema,outputSchemaandannotations.Return via
toolResult(...)so markdown/JSON handling and the character limit stay consistent; catch errors witherrorResult(...).Add the registration call in
src/index.tsand a test intest/.
Troubleshooting
Symptom | Cause |
Client shows no tools | Wrong path in the config, or the project was not built ( |
| The key is missing from the client's |
| The path is outside |
| The model ID does not exist for your key — run |
| 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 toolsopenai_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 OpenAIAIdempotent
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 modelsARead-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 OpenAIARead-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 OpenAIAIdempotent
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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Generate AI video, images and audio, and browse your history, from any MCP client.
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
Related MCP Servers
- -licenseCqualityNot gradedmaintenanceEnables 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-
- FlicenseBqualityDmaintenanceEnables interaction with OpenAI's Chat Completion and Assistants APIs, supporting assistant management, file operations, and direct queries to GPT models through standardized MCP tools.92-
- AlicenseBqualityDmaintenanceEnables MCP-compatible clients to leverage OpenAI's multimodal capabilities (vision, image generation, speech-to-text, text-to-speech) through file-oriented tools with a security-first architecture.101MIT
- FlicenseNot gradedqualityDmaintenanceA 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.-