gpt5-mcp-server

nightness/gpt5-mcp-server

3.2

If you are the rightful owner of gpt5-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This document provides a comprehensive overview of an MCP server that integrates OpenAI's LLM capabilities, specifically GPT-5 models, for use with MCP-compatible AI assistants.

Tools
2
Resources
0
Prompts
0

LLM MCP Server

A modern Model Context Protocol (MCP) server providing access to OpenAI's GPT-5 models with optional web search capabilities.

🚀 Features

  • Two Powerful Tools: Standard queries and web-enhanced queries with real-time search
  • Latest GPT-5 Models: Support for gpt-5, gpt-5-mini, and gpt-5-nano
  • Proper MCP Implementation: Uses stdio transport following MCP best practices
  • Type-Safe & Tested: Full TypeScript support with comprehensive test coverage
  • Easy Integration: Works with Claude Desktop, Claude Code, and custom MCP clients

🛠️ Quick Start

  1. Install and setup:

    npm install
cp .env.example .env
# Add your OPENAI_API_KEY to .env

  2. Test it works:

    npx tsx examples/cli-client.ts "Hello! Introduce yourself."

  3. Run tests:

    npm test

🎯 Usage Examples

# Basic query
npx tsx examples/cli-client.ts "What is TypeScript?"

# Different models
npx tsx examples/cli-client.ts "Explain React hooks" --model gpt-5-mini

# Web search for current info
npx tsx examples/cli-client.ts "What's the weather in Paris?" --web-search

# Advanced reasoning
npx tsx examples/cli-client.ts "Solve this math problem: ..." --reasoning-effort high

See for more detailed usage examples.

🔧 Available Tools

llm_query - Standard Queries

Perfect for coding help, analysis, explanations, and general tasks.

Parameters:

  • prompt (required) - Your question or request
  • modelVariant - gpt-5 (default), gpt-5-mini, gpt-5-nano
  • reasoningEffort - minimal (default), low, medium, high
  • verbosity - low, medium (default), high
  • max_tokens - Maximum response length
  • instructions - Custom system instructions

llm_query_web - Web-Enhanced Queries

Same as llm_query but with real-time web search for current information.

Perfect for:

  • Weather and news
  • Current events
  • Live statistics
  • Recent documentation updates

🔗 Integration

This server integrates with various MCP clients:

  • - Native MCP support
  • - Professional development environment
  • - With MCP extensions
  • - Build your own

See for detailed setup instructions.

🧪 Development

Commands

npm run dev          # Development with file watching
npm run build        # Compile to JavaScript
npm run type-check   # TypeScript validation
npm run start        # Run the server directly
npm test             # Run tests (interactive)
npm run test:run     # Run tests once

Project Structure

├── src/
│   └── index.ts              # MCP server implementation
├── examples/
│   ├── cli-client.ts         # Feature-complete CLI client
│   └── README.md            # Detailed usage examples
├── tests/
│   └── server.test.ts        # Test suite (24+ tests)
├── .env.example              # Environment template
├── README.md                 # This file
├── INTEGRATIONS.md           # Integration guides
└── package.json              # ES module configuration

Testing

The project includes comprehensive test coverage:

  • ✅ Tool schema validation
  • ✅ Parameter processing
  • ✅ OpenAI API integration
  • ✅ Error handling
  • ✅ Response formatting

⚙️ Configuration

Create a .env file:

# Required: Your OpenAI API key
OPENAI_API_KEY=your-openai-api-key-here

🚨 Troubleshooting

Common Issues:

  • "Cannot find module" → Run npm install
  • "Must use import to load ES Module" → Use tsx instead of node
  • Environment variables not loading → Verify .env file exists with OPENAI_API_KEY
  • TypeScript errors → Run npm run type-check

Test manually:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npx tsx src/index.ts

🏗️ Architecture

This is a proper MCP server, not an HTTP API:

✅ MCP Protocol Compliant - Standard stdio transport
✅ Tool Discovery - Dynamic tool listing and schema validation
✅ Process Isolation - Each client gets its own server instance
✅ Type Safety - Full TypeScript integration
✅ No Network Dependencies - Works anywhere, no ports needed

❌ Not HTTP-based - No REST endpoints or web server
❌ Not WebSocket-based - Uses standard input/output

🤝 Contributing

  1. Make your changes
  2. Run tests: npm run test:run
  3. Type check: npm run type-check
  4. Build: npm run build
  5. Test manually: npx tsx examples/cli-client.ts "test query"

📄 License

MIT License - see the file for details.

A modern MCP server built with TypeScript and OpenAI's GPT-5 models