@boseong/mcp-openai-gpt5/README.md

MCP server for OpenAI GPT-5 API with dual interface support (simple + messages)

# @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)

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

### Using NPX (No Installation Required)

You can run the server directly with npx without installing:

```bash
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:

```bash
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)
```bash
# 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)
```bash
# 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:

```bash
# 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)
```json
{
  "mcpServers": {
    "gpt5": {
      "command": "npx",
      "args": ["@boseong/mcp-openai-gpt5"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}
```

#### Option 2: Full Name Configuration (Legacy)
```json
{
  "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:

```json
{
  "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

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

### Running Locally

```bash
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](https://github.com/yourusername/mcp-server-gpt5).