GPT-5 MCP Server (TypeScript)

An MCP server that exposes a gpt5_query tool for GPT-5 inference via OpenAI Responses API, with optional Web Search Preview. Supports per-call overrides for verbosity, reasoning effort, and other parameters.

日本語はこちら

Features

TypeScript MCP server using @modelcontextprotocol/sdk
gpt5_query tool
- web_search_preview integration (optional)
- verbosity (low|medium|high)
- reasoning.effort (low|medium|high)
- tool_choice (auto|none), parallel_tool_calls
- system prompt, model, max_output_tokens
Config via environment variables with per-call overrides

Quick Start

Install dependencies

pnpm i # or npm i / yarn

Configure environment

Create .env (or export env vars):

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5
OPENAI_MAX_RETRIES=3
OPENAI_TIMEOUT_MS=60000
REASONING_EFFORT=medium
DEFAULT_VERBOSITY=medium
WEB_SEARCH_DEFAULT_ENABLED=false
WEB_SEARCH_CONTEXT_SIZE=medium

Build and run

pnpm run build
pnpm start

For development (watch mode):

pnpm run dev

Using with MCP Clients (Claude Code, Claude Desktop)

This server speaks Model Context Protocol (MCP) over stdio and emits pure JSON to stdout, making it safe for Claude Code and Claude Desktop.

Prerequisites

Node.js 18+
OpenAI API key via .env or environment variable

Build

pnpm run build

Run directly (recommended)

Command: node
Args: dist/cli.js
CWD: repository root (required if you want .env to be loaded)

Example:

node dist/cli.js

Add to Claude Code (VS Code)

Command Palette → "Claude: Manage MCP Servers"
"Add server" with:
- Name: gpt5-mcp
- Command: node (or absolute path, e.g., /opt/homebrew/bin/node)
- Args: ["/absolute/path/to/gpt5-mcp-server/dist/cli.js"] (or just gpt5-mcp-server if installed globally)
- Env (choose one):
  - Option A (ENV_FILE): ENV_FILE=/absolute/path/to/gpt5-mcp-server/.env
  - Option B (explicit): set OPENAI_API_KEY, OPENAI_MODEL, OPENAI_TIMEOUT_MS, DEFAULT_VERBOSITY, REASONING_EFFORT, WEB_SEARCH_DEFAULT_ENABLED, WEB_SEARCH_CONTEXT_SIZE

Add to Claude Desktop Edit config (e.g., macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) and add:

Option A: using ENV_FILE

{
  "mcpServers": {
    "gpt5-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/absolute/path/to/gpt5-mcp-server/dist/cli.js"],
      "env": {
        "ENV_FILE": "/absolute/path/to/gpt5-mcp-server/.env"
      }
    }
  }
}

Option B: explicit env vars

{
  "mcpServers": {
    "gpt5-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/absolute/path/to/gpt5-mcp-server/dist/cli.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_MODEL": "gpt-5",
        "OPENAI_TIMEOUT_MS": "120000",
        "DEFAULT_VERBOSITY": "medium",
        "REASONING_EFFORT": "low",
        "WEB_SEARCH_DEFAULT_ENABLED": "false",
        "WEB_SEARCH_CONTEXT_SIZE": "medium"
      }
    }
  }
}

CLI usage

Package exposes bin(s).
- Local link: npm link → run gpt5-mcp-server
- Global (after publish): npm i -g gpt5-mcp-server → gpt5-mcp-server
- Direct: node /absolute/path/to/gpt5-mcp-server/dist/cli.js

Web Search notes

Due to OpenAI constraints, web_search_preview cannot be combined with reasoning.effort = minimal.
This server automatically bumps effort to medium if web_search.enabled = true.
If you need strict minimal, set web_search.enabled = false.

Troubleshooting

JSON parse error (Unexpected token ...)
- Likely extra logs on stdio. Use node dist/cli.js, avoid npx.
Auth error
- Ensure OPENAI_API_KEY is provided.
Timeout
- Increase OPENAI_TIMEOUT_MS (e.g., 120000).
400 with Web Search
- Caused by minimal effort + web search. It's auto-bumped to medium; alternatively set reasoning_effort=medium or disable web_search.

Tool: gpt5_query

Input schema (JSON):

{
  "query": "string",
  "model": "string?",
  "system": "string?",
  "reasoning_effort": "low|minimal|medium|high?",
  "verbosity": "low|medium|high?",
  "tool_choice": "auto|none?",
  "parallel_tool_calls": "boolean?",
  "max_output_tokens": "number?",
  "web_search": {
    "enabled": "boolean?",
    "search_context_size": "low|medium|high?"
  }
}

Example call (Inspector or client):

{
  "method": "tools/call",
  "params": {
    "name": "gpt5_query",
    "arguments": {
      "query": "Summarize the latest on X.",
      "verbosity": "low",
      "web_search": { "enabled": true, "search_context_size": "medium" }
    }
  }
}

Defaults and behavior

model: defaults to OPENAI_MODEL (env). Example: gpt-5.
system: optional. Sent as instructions.
reasoning_effort: accepts low|minimal|medium|high. Internally low → minimal。
- Constraint: when web_search.enabled=true and effort is minimal, it is auto-bumped to medium to satisfy OpenAI constraints.
verbosity: defaults to DEFAULT_VERBOSITY (env). Sent as text.verbosity.
tool_choice: default auto.
parallel_tool_calls: default true.
max_output_tokens: optional; omitted when not set.
web_search.enabled: defaults to WEB_SEARCH_DEFAULT_ENABLED (env).
web_search.search_context_size: defaults to WEB_SEARCH_CONTEXT_SIZE (env). Allowed: low|medium|high.

Environment variable mapping

OPENAI_API_KEY (required)
OPENAI_MODEL → model default
OPENAI_MAX_RETRIES → OpenAI client
OPENAI_TIMEOUT_MS → OpenAI client
REASONING_EFFORT → reasoning_effort default (low|minimal|medium|high)
DEFAULT_VERBOSITY → verbosity default (low|medium|high)
WEB_SEARCH_DEFAULT_ENABLED → web_search.enabled default (true|false)
WEB_SEARCH_CONTEXT_SIZE → web_search.search_context_size default (low|medium|high)

Output shape

On success: content: [{ type: "text", text: string }]
On error: isError: true and a text item with Error: ...

Notes

If the selected model does not support certain fields (e.g., verbosity), they are ignored.
Keep API keys out of logs. Ensure .env is not committed.

License

MIT

日本語 (Japanese)

ツール: gpt5_query

入力スキーマ (JSON):

{
  "query": "string",
  "model": "string?",
  "system": "string?",
  "reasoning_effort": "low|minimal|medium|high?",
  "verbosity": "low|medium|high?",
  "tool_choice": "auto|none?",
  "parallel_tool_calls": "boolean?",
  "max_output_tokens": "number?",
  "web_search": {
    "enabled": "boolean?",
    "search_context_size": "low|medium|high?"
  }
}

例 (Inspector など):

{
  "method": "tools/call",
  "params": {
    "name": "gpt5_query",
    "arguments": {
      "query": "Summarize the latest on X.",
      "verbosity": "low",
      "web_search": { "enabled": true, "search_context_size": "medium" }
    }
  }
}

既定値と挙動

model: 既定は OPENAI_MODEL（環境変数）。例: gpt-5。
system: 任意。OpenAI には instructions として送信します。
reasoning_effort: low|minimal|medium|high を受け付け、内部的に low は minimal として扱われます。
- 制約: web_search.enabled=true かつ effort=minimal の場合、OpenAI の制約に合わせて自動的に medium に引き上げます。
verbosity: 既定は DEFAULT_VERBOSITY（環境変数）。OpenAI には text.verbosity として送信します。
tool_choice: 既定は auto。
parallel_tool_calls: 既定は true。
max_output_tokens: 任意。未指定の場合は送信しません。
web_search.enabled: 既定は WEB_SEARCH_DEFAULT_ENABLED（環境変数）。
web_search.search_context_size: 既定は WEB_SEARCH_CONTEXT_SIZE（環境変数）。許容値: low|medium|high。

環境変数マッピング

OPENAI_API_KEY（必須）
OPENAI_MODEL → model 既定
OPENAI_MAX_RETRIES → OpenAI クライアント設定
OPENAI_TIMEOUT_MS → OpenAI クライアント設定
REASONING_EFFORT → reasoning_effort 既定（low|minimal|medium|high）
DEFAULT_VERBOSITY → verbosity 既定（low|medium|high）
WEB_SEARCH_DEFAULT_ENABLED → web_search.enabled 既定（true|false）
WEB_SEARCH_CONTEXT_SIZE → web_search.search_context_size 既定（low|medium|high）

出力形式

成功時: content: [{ type: "text", text: string }]
エラー時: isError: true と text に Error: ...

注意

選択したモデルが特定のフィールド（例: verbosity）をサポートしない場合、それらは無視されます。
API キーはログに出力しません。.env はコミットしないでください。

MCP Serverの使い方

このサーバーは Model Context Protocol (MCP) の標準入出力（stdio）で動作します。純粋な JSON のみを stdout に出力する設計のため、MCP Inspector / Claude Code / Claude Desktop で安全に接続できます。

前提

Node.js 18+
OpenAI APIキーが .env もしくは環境変数で設定されていること

ビルド

pnpm run build

直接起動（推奨）

コマンド: node
引数: dist/cli.js
CWD: リポジトリのルート（.env を読む場合は必須）

例:

node dist/cli.js

Claude Code（VS Code 拡張）に追加

VS Code のコマンドパレット → 「Claude: Manage MCP Servers」
「Add server」で次を入力:
- Name: gpt5-mcp
- Command: node（絶対パス可）
- Args: ["/絶対/パス/gpt5-mcp-server/dist/cli.js"]（グローバル導入済みなら不要）
- Env（どちらか一方）:
  - オプションA（ENV_FILE）: ENV_FILE=/絶対/パス/gpt5-mcp-server/.env
  - オプションB（明示指定）: OPENAI_API_KEY、OPENAI_MODEL、OPENAI_TIMEOUT_MS、DEFAULT_VERBOSITY、REASONING_EFFORT、WEB_SEARCH_DEFAULT_ENABLED、WEB_SEARCH_CONTEXT_SIZE

Claude Desktop に追加設定ファイル（例: macOS は ~/Library/Application Support/Claude/claude_desktop_config.json）を編集して以下を追記します。

オプションA: ENV_FILE を使う

{
  "mcpServers": {
    "gpt5-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/絶対/パス/gpt5-mcp-server/dist/cli.js"],
      "env": {
        "ENV_FILE": "/絶対/パス/gpt5-mcp-server/.env"
      }
    }
  }
}

オプションB: 環境変数を明示指定

{
  "mcpServers": {
    "gpt5-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/絶対/パス/gpt5-mcp-server/dist/cli.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_MODEL": "gpt-5",
        "OPENAI_TIMEOUT_MS": "120000",
        "DEFAULT_VERBOSITY": "medium",
        "REASONING_EFFORT": "low",
        "WEB_SEARCH_DEFAULT_ENABLED": "false",
        "WEB_SEARCH_CONTEXT_SIZE": "medium"
      }
    }
  }
}

CLI の利用

パッケージには bin が含まれます。
- ローカルリンク: npm link 後に gpt5-mcp-server
- グローバル（公開後）: npm i -g gpt5-mcp-server → gpt5-mcp-server
- 直接実行: node /絶対/パス/gpt5-mcp-server/dist/cli.js

Web Search に関する注意

OpenAI の制約により、web_search_preview は reasoning.effort = minimal と併用できません。
本サーバーは web_search.enabled = true の場合、自動的に effort を medium に引き上げて呼び出します。
もし minimal を厳格に使いたい場合は、web_search.enabled = false にしてください。

トラブルシューティング

JSON パースエラー（Unexpected token ...）
- stdio に余計な出力が混ざっている可能性があります。node dist/cli.js を使い、npx は避けてください。
- .env 読み込みやライブラリのログは既に抑止済みです。
認証エラー
- OPENAI_API_KEY が正しく渡っているか確認。
タイムアウト
- OPENAI_TIMEOUT_MS を増やす（例: 120000）。
Web Search で 400 エラー
- reasoning.effort=minimal と web_search の併用不可が原因。自動的に medium に上げますが、明示的に medium を指定するか、web_search を無効化してください。

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/workflows		.github/workflows
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Uh oh!

Repository files navigation

GPT-5 MCP Server (TypeScript)

Features

Quick Start

Using with MCP Clients (Claude Code, Claude Desktop)

Tool: gpt5_query

Notes

License

日本語 (Japanese)

ツール: gpt5_query

MCP Serverの使い方

About

Uh oh!

Releases

Packages

Languages

Uh oh!

Uh oh!

gotalab/gpt5-mcp-server

Folders and files

Latest commit

History

Repository files navigation

GPT-5 MCP Server (TypeScript)

Features

Quick Start

Using with MCP Clients (Claude Code, Claude Desktop)

Tool: gpt5_query

Notes

License

日本語 (Japanese)

ツール: gpt5_query

MCP Serverの使い方

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages