@boseong/mcp-openai-gpt5

MCP (Model Context Protocol) server for OpenAI GPT-5 API integration with dual interface support. This server provides two complementary ways to interact with OpenAI's GPT-5 models through the MCP protocol.

Features

• Dual Interface Support: Two complementary tools for different use cases
  • gpt5_generate: Simple text generation with prompts
  • gpt5_messages: Structured conversations with message arrays
• Flexible Configuration: Support for reasoning effort levels (low, medium, high)
• Comprehensive Parameters: Temperature, top-p, token limits, system instructions
• Detailed Usage Tracking: Token consumption reporting for both prompt and completion
• Smart Environment Handling: Multiple .env file location support for different deployment scenarios

What Makes This Different

This server differs from existing GPT-5 MCP implementations by providing:

1. Two Distinct Tools: Unlike single-tool servers, this provides both simple and structured interfaces
2. Enhanced Token Reporting: Detailed usage statistics including prompt/completion/total tokens
3. Flexible Environment: Supports multiple .env file locations for various deployment setups
4. Message-First Design: Built specifically for structured conversation workflows

Installation

Using NPM (Global Installation)

npm install -g @boseong/mcp-openai-gpt5

Using NPX (No Installation Required)

You can run the server directly with npx without installing:

npx @boseong/mcp-openai-gpt5

Configuration

Setting up OpenAI API Key

You need an OpenAI API key to use this server. You can set it in two ways:

Option 1: Environment Variable

Set the OPENAI_API_KEY environment variable:

export OPENAI_API_KEY=your-api-key-here

Option 2: Claude Desktop Configuration

Add the API key directly in your Claude Desktop configuration file.

Claude Code Integration

To use this server with Claude Code, you can use either gpt5 or openai-gpt5 as the server name. Use the mcp add command:

Option 1: Short Name (Recommended)

# Add the MCP server using the short name "gpt5"
claude mcp add gpt5 --env OPENAI_API_KEY=your-openai-api-key-here \
  -- npx @boseong/mcp-openai-gpt5

Option 2: Full Name (Legacy)

# Add the MCP server using the full name "openai-gpt5"
claude mcp add openai-gpt5 --env OPENAI_API_KEY=your-openai-api-key-here \
  -- npx @boseong/mcp-openai-gpt5

Or using the add-json command for more complex configuration:

# Using short name
claude mcp add-json gpt5 --scope user '{
  "command": "npx",
  "args": ["@boseong/mcp-openai-gpt5"],
  "env": {
    "OPENAI_API_KEY": "your-openai-api-key-here"
  }
}'

# Using full name
claude mcp add-json openai-gpt5 --scope user '{
  "command": "npx",
  "args": ["@boseong/mcp-openai-gpt5"],
  "env": {
    "OPENAI_API_KEY": "your-openai-api-key-here"
  }
}'

Claude Desktop Integration

To use this server with Claude Desktop, add it to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

You can use either gpt5 (recommended) or openai-gpt5 as the server key:

Option 1: Short Name Configuration (Recommended)

{
  "mcpServers": {
    "gpt5": {
      "command": "npx",
      "args": ["@boseong/mcp-openai-gpt5"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

Option 2: Full Name Configuration (Legacy)

{
  "mcpServers": {
    "openai-gpt5": {
      "command": "npx",
      "args": ["@boseong/mcp-openai-gpt5"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

If you installed globally, you can also use:

{
  "mcpServers": {
    "gpt5": {
      "command": "mcp-openai-gpt5",
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

Available Tools

gpt5_generate

Simple text generation with a prompt.

Parameters:

• input (required): The prompt text
• model (optional): Model variant (default: "gpt-5")
• instructions (optional): System instructions for the model
• reasoning_effort (optional): "low" | "medium" | "high"
• max_tokens (optional): Maximum tokens to generate
• temperature (optional): 0-2 range for randomness
• top_p (optional): 0-1 range for nucleus sampling

gpt5_messages

Structured conversation with message arrays.

Parameters:

• messages (required): Array of conversation messages
  • role: "user" | "developer" | "assistant"
  • content: Message content
• Same optional parameters as gpt5_generate

Usage Examples

Once configured in Claude Desktop, you can use the GPT-5 tools directly in your conversations:

1. Simple generation: Ask Claude to use GPT-5 to generate text
2. Conversation mode: Use GPT-5 with structured messages for multi-turn conversations
3. Reasoning tasks: Enable high reasoning effort for complex problems

Development

Building from Source

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

Running Locally

npm start

Requirements

• Node.js >= 18.0.0
• OpenAI API key with GPT-5 access

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please visit the GitHub repository.