openai-mcp-server

OpenAI API를 모든 MCP 클라이언트 — Claude Desktop, Claude Code, Cowork, Cursor, 또는 이 프로토콜을 지원하는 어떤 클라이언트든 — 에 통합해 주는 MCP 서버입니다.

제공 도구는 아홉 가지입니다: 텍스트 생성, chat completions, 모델 탐색, 이미지 생성 및 편집, 전사, 음성 합성, 임베딩, 콘텐츠 조정.

이 서버가 필요한 이유

Claude 플러그인 카탈로그에는 공식 OpenAI 플러그인이 없습니다. 이 서버는 그에 대응하는 역할을 하며, 소유하고 확장할 수 있는 일반적인 오픈소스 프로젝트로 빌드되었습니다.

Related MCP server: OpenAI Assistant MCP Server

도구

모든 도구는 response_format: "markdown" | "json"을 받습니다. markdown은 읽기용, json은 처리용입니다. 또한 모든 도구가 structuredContent를 반환하므로, 출력 스키마를 이해하는 클라이언트는 파싱 없이 타입이 지정된 데이터를 얻을 수 있습니다.

요구 사항

• 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 안쪽의 절대 경로만 허용합니다. 경로를 검사하 V? — 바이너리 출략은 영원히 대화 안으로 들집 않겠니다. 이미지, 사운드, 임베딩 벡터는 디스크에 저장되고 경로만 반환됩니다. 그렇지 않으면 단일 base64 PNG 또는 3072채 실수 벡터 하나가 모델의 컨텍스트 창을 틀어막일 것입니다.

API 키는 환경변수에서만 읽히며, 도구 인자, 로그 줄, 오류 메시지에는 절대 나타나지 않습니다.

예시

자연어로 MCP 클라이언트에 요청하면 클라이언트가 도구를 선택합니다.

"이 텍스트를 세 문장으로 요약해 주세요."

→ 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()와 .describe()를 적용한 Zod 스키마를 작성합니다.

2. server.registerTool(name, config, handler)에 등록합니다 — title, description, inputSchema, outputSchema, annotations를 포함해야 합니다.

3. toolResult(...)로 반환하여 markdown/JSON 처리와 글자 수 제한이 일관되도록 하고, 오류는 errorResult(...)로 처리합니다.

4. 등록 호출을 src/index.ts에 추가하고 test/에 테스트를 작성합니다.

문제 해결

서버는 stderr에 로그를 쓰며, stdout은 JSON-RPC 스트림을 전달하므로 항상 깨끗하게 유지해야 합니다.

라이선스

MIT