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

MCP server for OpenAI GPT-5 API integration

# @boseong/mcp-server-gpt5

MCP (Model Context Protocol) server for OpenAI GPT-5 API integration. This server allows Claude Desktop to interact with OpenAI's GPT-5 models through the MCP protocol.

## Features

- Simple text generation with GPT-5
- Structured conversation with message arrays
- Support for reasoning effort levels (low, medium, high)
- Configurable temperature and token limits
- Token usage tracking

## Installation

### Using NPM (Global Installation)

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

### Using NPX (No Installation Required)

You can run the server directly with npx without installing:

```bash
npx @boseong/mcp-server-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, use the `mcp add` command:

```bash
# Add the MCP server with environment variable
claude mcp add gpt5 --env OPENAI_API_KEY=your-openai-api-key-here \
  -- npx @boseong/mcp-server-gpt5
```

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

```bash
claude mcp add-json gpt5 --scope user '{
  "command": "npx",
  "args": ["@boseong/mcp-server-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`

Add the following configuration:

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

Or if you installed globally:

```json
{
  "mcpServers": {
    "gpt5": {
      "command": "mcp-server-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).