# openai-mcp-server

Un servidor [mcp](https://modelcontextprotocol.io) que introduces la API de OpenAI en cualquera cliente MCP — Claude Desktop, Claude Code, Cowork, Cursor, o cualquera ora cosa use the protocolo.

Nueve herramientas: génación de texto, chat completions, descubrimiento de models, generación and edición de images, transición; **...**

No. Let's follow original exactly.

I'll output in Spanish, with proper accents and correct syntax.

I will be careful, translate the whole.

Need avoid typos like "transcr". We'll produce Excel.

Final draft:

---

# openai-mcp-server

Un servidor [MCP](https://modelcontextprotocol.io) que integra la API de OpenAI en cualquier cliente MCP — Claude Desktop, Claude Code, Cowork, Cursor, o cualquier otra cosa que hable con el protocolo.

Nueve herramientas: generación de texto, finalización de chat, descubrimiento de modelos, generación y edición de imágenes, transcripción, síntesis de voz, colocación de embeddings, y moderación.

Wait, "chat completions" I'll keep as "completions de chat"? Let's decide.

Given the instruction "Product names verbatim", I will keep "chat completions" as literal term. But "read-only" translation.

Nueve herramientas: generación de texto, chat completions, descubrimiento de models, generación e edición de imágenes, transcripción, síntesis de voz, embeddings and moderación.

### Tools table:

Now render elegantly.

Let's produce:

# openai-mcp-server

Un servidor [mcp](...) que...

## Herramientas

| herramienta | qué hace | solo lectura |
| --- | --- | --- |
| `openai_generate_text` | Genera text via the API de Responses — instrucciones, effort de razonamiento, JSON exigido, encadenamiento de body respuests | no |
| `openai_chat_completion` | Envía an historial of explícito mensaje a través de Chat Completions | no |
...

Note "solo lectura" is "Read-only". In header "Solo lectura". Fina.

Let's list descriptions:

`openai_list_models` | "Lista los IDs de modelos que tu clave usua puede use, filtered y paginated" 

`openai_generate_image` | "Crea imágenes a partir de unmencion and write in disk" (No)

`openai_edit_image` | "Edit or combine existing images, optionally with mask" 

`openai_transcribe_audio` | "Transcribes a audio local file"

`openai_text_to_speech` | "Synthesises voz to a speech file"

`openai_create_embeddings` | "Genera embeddings de text for búsqueda semántic, escrit en JSON"

`openai_moderate_content` | "Compue a text contra el policy de moderción of Opanai"

After table:

"Todas la herramientas acepta `response_format: "markdown" | "json"` — markdown para lectura, json para pprocessamento. Todas also devuelve `structuredContent`, de form que el cliente que entiende esquemas de salida reciben data tipados sin parser."

Now I'll write one final, carefully. Let's craft the entire final text in final answer.# openai-mcp-server

Un servidor [MCP](https://modelcontextprotocol.io) que integra la API de OpenAI en cualquiera cliente MCP — Claude Desktop, Claude Code, Cowork, Cursor, u otrás that the the protoco.

Nueve herramientas: generación de texto, chat completions, descubrimiento de models, generción e edición de imáges, transcripción, síntesis de voz, embeddings y moderación.

## For qué existe?

There is no oficial plugin de OpenAI en el catálog de complementos de Claude. Este servidor es el equivamente, cread or as un project open source que tú puedes poseer y extend.

## Herramientas

| Herramienta | Qué hace | Solo lectura |
| -------------------------- | ---------------------------------------------------------------------------------------------------- | --------- |
| `openai_generate_text`     |Genera text amidst via de Responses API — instrucciones, superior de razonamiento, JSON forzado, cadena de resuestas | no |
| `openai_chat_completion` |Enví a historial of mensajes explícitos via the Chat Completions | no |
| `openai_list_models` | Lista los model IDs que tu key puede usa, filtro and and paginá | sí |
| `openai_generate_image` | Crea imágenes a partir of a un prompt, escríbe en disco | no |
| `openai_edit_image` | Edita or combine images existing, opcionalmente con a maskara | no |
| `openai_transcribe_audio` | Trscribe a archivo de audio local | no |
| `openai_text_to_speech` | Sintetiza voice in a archivo de audio | no |
| `openai_create_embeddings` | Genera the embeddings de texts for semántic búsqueda, escríbe en JSON | no |
| `openai_moderate_content` |Evalúa text in función de política de moderación of OpenAI | sí |

All herramientas accept `response_format: "markdown" | "json"` — markdown for reading, JSON para processing. All also return `structuredContent`, so which recently clients who understand the output schema received data with parsar without.

## Requisitos

* Node.js 20 o superior
* Una key de OpenAI with available cuota

## Installation

GXP1

Verificar la compilión:

GXP2

##Configura tu cliente MCP

El servidor habla MCP vía **stdio**, as que el client lo throws as subprocess.

### Claude Desktop

Edita `claude_desktop_config.json`:

* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APDATADATA%\Claude\claude_desktop_config.json`

GXP3

Reinicia Claude Desktop.

### Claude Code

GXP4

### Cualquier otro cliente MCP

Configura lo apuntando a `node /abs/path/to/dist/index.js` with `OPENAI_API_KEY` in el environment.

## Configuración

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

| Variable                             |Predeterminado                  | Proposito                                                |
| ------------------------------------ | ------------------------ | ---------------------------------------------------------- |
| `OPENAI_API_KEY`                     | —                        | **Required.** Tu clava de OpenAI        |
| `OPENAI_BASE_URL`                    | OpenAI's default| Al themativo endpoint (Azure, gateway, proxy)  |
| `OPENAI_ORG_ID` | — | organization ID |
| `OPENAI_PROJECT_ID` | — | ID de project |
| `OPENAI_MCP_OUT_PUT_DIR` | `<tmp>/openai-mcp` | Dónde se escriben file generados                     |
| `OPENAI_MCP_ALLOWED_DIRS` | solo directório output | The absolute folder separated by colon that server may **read** from                    |
| `OPENAI_MCP_TIMEOUT_MS`              | `12000` | temporarily per request         |
| `OPENAI_MCP_MAX_RETRIES`             | `2` | attempts failures |
| `OPENAI_DEFAULT_TEXT_MODEL`          | `gpt-5.6-terra` |Default text model |
| `OPENAI_DEFAULT_IMAGE_MODEL`         | `gpt-images` | default image model |
| `OPENAI_DEFAULT_EMBEDDING_MODEL`     | `text-embedding-3-small` | model embedding pred |
| `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 model moderation |

**Model se changes.** OpenI adds, rename, retros, and access difere per project. `openai_list_models` disponible todo predire de dire.. "model not found" — ** start there.

## Security Model

**The:al system is sandboxed.** Tools that read local files (`openai_edit_image`, ` openai_text`, `openai_transcribe_audio`) only accept below absolute paths inside `OPENAI_MCP_ALLOW_DINS`. Relateds are and demonized with `realpath` before the check, so so symlinks and `../` cannot escape. The output directory is always permission; no other, until you add it. Keep that list narrow.

**The output is never in the conversation.** "Images, audio and embedding vectors are written in disk and only their paths returned. A simplle base64 PNG or a vector of 3072 float would form el flood**Windows**context window.C, and cannot.

The key only reads from the environment; never appears in a tool argument, a log line, or an error message.

## Examples

For in your MCP client "Use the OpenAI server to summarize this text in three sentences." -> `openai_text_gen` "Which OpenAI embedding models can I use?" -> `openai_list_models` with `filter="embed"` "Generate a transparent PNG logo of a blue fox." -> `openai_generate_image` with `background="transparent"` "Transcribe \~/... in German." -> `openai_transcribe_audio` with `language="de"` requires directory in `OPENAI_MCP_ALLOW_DIRS` for mark.

## Development

GXP5

Test suite trunks configuration, sandbox symlink, error and response, never contact OpenAI. the.

### Project layout

GXP6

### Adding a tool

1. Write Zod schema with `.strict()` and `.describe()`,
2. `server.registerTool(name, handler)` with `title`, `description`, `schema`.
3. Return `toolResult(...)`, catch with `errorResult(...)`.
4. Call in `src/index.ts` and test `test/`.

## Troubleshooting

| Symptom | Cause |
| --- | --- |
| No tools | Wrong path, or `npm run build` missing |
| `Configuration error: OPENAI_API_KEY is not set` (78) | missing in `env` |
| `Error: Access ... is not permitted` | outside `OPENAI_CP_ALLOW_` |
| `not f` on generation | model wrong |
| `Error: Rate `or` quota exceeded | retray later, check your project billing |

Logging stderr, stdout for JSON.

## Licencia

MIT — see [LICENSE](LICENSE).