GPT-5 MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with OpenAI's GPT-5 API through Claude Code. This server enables you to leverage GPT-5's advanced capabilities directly within your Claude Code workflows.

🚀 Features

Direct GPT-5 Integration: Call GPT-5 API with simple prompts or structured conversations
Two Powerful Tools:
- gpt5_generate: Simple text generation with prompts
- gpt5_messages: Structured conversation handling with message arrays
Built for Claude Code: Optimized for seamless integration with Anthropic's Claude Code IDE
TypeScript Support: Fully typed for better development experience
Error Handling: Robust error handling with detailed feedback
Usage Tracking: Built-in token usage reporting

📋 Prerequisites

Node.js (v18 or higher)
OpenAI API key with GPT-5 access
Claude Code IDE

🛠 Installation

1. Clone the Repository

git clone https://github.com/AllAboutAI-YT/gpt5mcp.git
cd gpt5mcp

2. Install Dependencies

cd servers/gpt5-server
npm install

3. Build the Server

npm run build

4. Configure Environment Variables

Create a .env file in the servers directory:

# servers/.env
OPENAI_API_KEY=your-openai-api-key-here

🔧 Claude Code Integration

Add the Server to Claude Code

claude mcp add gpt5-server -e OPENAI_API_KEY=your-openai-api-key-here -- node /path/to/gpt5mcp/servers/gpt5-server/build/index.js

Verify Installation

Test the server with a simple query:

Ask GPT-5: "Hello, how are you today?"

📚 Available Tools

`gpt5_generate`

Generate text using a simple input prompt.

Parameters:

input (required): The text prompt for GPT-5
model (optional): GPT-5 model variant (default: "gpt-5")
instructions (optional): System instructions for the model
reasoning_effort (optional): Reasoning level ("low", "medium", "high")
max_tokens (optional): Maximum tokens to generate
temperature (optional): Randomness level (0-2)
top_p (optional): Top-p sampling parameter (0-1)

`gpt5_messages`

Generate text using structured conversation messages.

Parameters:

messages (required): Array of conversation messages with role and content
model (optional): GPT-5 model variant (default: "gpt-5")
instructions (optional): System instructions for the model
reasoning_effort (optional): Reasoning level ("low", "medium", "high")
max_tokens (optional): Maximum tokens to generate
temperature (optional): Randomness level (0-2)
top_p (optional): Top-p sampling parameter (0-1)

Message Format:

{
  "messages": [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "What about Germany?"}
  ]
}

🎯 Usage Examples

Simple Text Generation

// Using the gpt5_generate tool
{
  "input": "Explain quantum computing in simple terms",
  "reasoning_effort": "high",
  "max_tokens": 500
}

Conversation Handling

// Using the gpt5_messages tool
{
  "messages": [
    {"role": "user", "content": "I'm learning Python. Can you help?"},
    {"role": "assistant", "content": "I'd be happy to help you learn Python! What specific topic would you like to start with?"},
    {"role": "user", "content": "Let's start with variables and data types."}
  ],
  "instructions": "Be a helpful Python tutor",
  "reasoning_effort": "medium"
}

📁 Project Structure

gpt5mcp/
├── servers/
│   └── gpt5-server/
│       ├── src/
│       │   ├── index.ts          # Main server implementation
│       │   └── utils.ts          # GPT-5 API utilities
│       ├── build/                # Compiled TypeScript output
│       ├── package.json          # Dependencies and scripts
│       └── tsconfig.json         # TypeScript configuration
├── CLAUDE.md                     # Claude Code configuration
├── GPT5-MCP-Server-Guide.html    # Interactive setup guide
├── .gitignore                    # Git ignore patterns
└── README.md                     # This file

🛡️ Security

API keys are loaded from environment variables (never hardcoded)
The .env file is automatically excluded from version control
All API communications use secure HTTPS
Error messages don't expose sensitive information

🔄 Development

Scripts

npm run build: Compile TypeScript and set permissions
npm run start: Start the compiled server
npm run dev: Build and start in development mode

Making Changes

Edit TypeScript files in src/
Run npm run build to compile
Restart Claude Code MCP server if needed

🐛 Troubleshooting

Common Issues

Server not found in Claude Code:

# Remove and re-add the server
claude mcp remove gpt5-server
claude mcp add gpt5-server -e OPENAI_API_KEY=your-key -- node /path/to/build/index.js

API Key Issues:

Ensure your OpenAI API key has GPT-5 access
Verify the key is correctly set in the .env file
Check that the environment variable is properly loaded

Build Errors:

# Clean rebuild
rm -rf build/
npm run build

📖 Interactive Guide

Open GPT5-MCP-Server-Guide.html in your browser for an interactive, step-by-step setup guide with copy-paste commands.

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes and test thoroughly
Commit your changes: git commit -m 'Add feature-name'
Push to the branch: git push origin feature-name
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Model Context Protocol (MCP) by Anthropic
Powered by OpenAI's GPT-5 API
Created for the Claude Code community

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: MCP Documentation

⭐ Star this repo if you found it helpful!

GPT-5