jsindy/mcp-openai

MCP OpenAI Server

A Model Context Protocol (MCP) server that enables Claude CLI to seamlessly consult OpenAI models when encountering challenging problems. This integration allows Claude to maintain its conversation context while leveraging OpenAI's models (such as o3, o1, or gpt-4) for alternative perspectives or specialized assistance.

Features

• Seamless Integration: Claude CLI can request help from OpenAI models without losing context
• Intelligent Model Selection: Fuzzy search and dynamic model discovery
• Token Management: Automatic context window tracking and warnings
• Rate Limiting: Implements OpenAI's recommended patterns with exponential backoff
• Streaming Support: Real-time response streaming for better user experience
• Error Handling: Graceful error recovery with automatic retries

Prerequisites

• Node.js 18.0.0 or higher
• An OpenAI API key with access to the models you want to use
• Claude CLI configured for MCP server support

Installation

1. Clone the Repository

git clone https://github.com/jsindy/mcp-openai.git
cd mcp-openai

2. Install Dependencies

npm install

3. Set up Environment Variables

Create a .env file in the root directory:

cp .env.example .env

Edit the .env file and add your OpenAI API key:

OPENAI_API_KEY=sk-your-api-key-here

4. Build the Project

npm run build

Configuration

Required Environment Variables

• OPENAI_API_KEY - Your OpenAI API key (required)

Optional Environment Variables

• OPENAI_DEFAULT_MODEL - Default model to use when none specified (default: gpt-4-turbo-preview)
• OPENAI_BASE_URL - Custom base URL for OpenAI API (useful for proxies)
• OPENAI_ORGANIZATION - Your OpenAI organization ID
• OPENAI_MAX_RETRIES - Maximum number of retry attempts (default: 5)
• OPENAI_TIMEOUT - Request timeout in milliseconds (default: 30000)
• OPENAI_DEFAULT_MAX_TOKENS - Default max tokens for responses (default: 4096)
• OPENAI_TEMPERATURE - Default temperature for model responses (default: 0.7)

Example .env Setup

# Required
OPENAI_API_KEY=sk-your-api-key-here

# Optional
OPENAI_DEFAULT_MODEL=gpt-4-turbo-preview
OPENAI_ORGANIZATION=org-your-org-id
OPENAI_MAX_RETRIES=5
OPENAI_TIMEOUT=30000
OPENAI_DEFAULT_MAX_TOKENS=4096
OPENAI_TEMPERATURE=0.7

Usage with Claude CLI

Adding MCP Server to Claude CLI

You can add the MCP OpenAI server to Claude CLI either globally (user scope) or locally (project scope).

Option 1: Global Installation (Recommended)

Add the server to your global Claude CLI configuration so it's available in all sessions:

# Add to global config with environment variable for API key
claude mcp add --scope user openai node /path/to/mcp-openai/dist/index.js -e OPENAI_API_KEY=$OPENAI_API_KEY

# Or if you prefer to use the .env file in the mcp-openai directory
claude mcp add --scope user openai node /path/to/mcp-openai/dist/index.js

Option 2: Local Installation

Add the server only to the current project:

# Add to local project config
claude mcp add openai node /path/to/mcp-openai/dist/index.js -e OPENAI_API_KEY=$OPENAI_API_KEY

Verify Installation

Check that the server was added successfully:

claude mcp list
# Should show: openai: node /path/to/mcp-openai/dist/index.js

Remove Server (if needed)

To remove the server from your configuration:

# Remove from global config
claude mcp remove --scope user openai

# Remove from local config
claude mcp remove openai

2. Start Claude CLI

Once configured, simply start Claude CLI:

claude

The MCP OpenAI server will automatically start when needed.

3. Example Interactions

When Claude encounters a challenging problem, it can consult OpenAI models:

User: Help me optimize this complex TypeScript generic type that's causing performance issues.

Claude: This is a complex type inference issue. Let me consult OpenAI's o3 model for additional perspective.
[Claude invokes askOpenAI tool]

Claude: Based on OpenAI's analysis, the issue stems from recursive type instantiation. Here's an optimized solution...

Available Tools

1. askOpenAI

Consults an OpenAI model with a specific context or question.

Parameters:

• model (optional): The OpenAI model to use (e.g., "o3", "gpt-4", "gpt-4-turbo")
• context (required): The problem context or question to send to OpenAI
• systemPrompt (optional): Custom system prompt to guide the model's behavior
• includeConversationHistory (optional): Whether to include previous exchanges (default: false)
• maxTokens (optional): Maximum tokens for the response

Example Usage:

// Basic usage
await askOpenAI({
  context: "Explain the differences between TypeScript conditional types and mapped types"
});

// With specific model
await askOpenAI({
  model: "o3",
  context: "Debug this complex React hooks race condition: [code snippet]",
  systemPrompt: "You are an expert React developer specializing in concurrent rendering."
});

// With token limit
await askOpenAI({
  model: "gpt-4-turbo",
  context: "Analyze this architecture design...",
  maxTokens: 2000
});

2. listOpenAIModels

Lists all available OpenAI models and their capabilities.

Parameters:

• filter (optional): Filter models by name pattern

Example Usage:

// List all available models
await listOpenAIModels();

// Filter for specific models
await listOpenAIModels({ filter: "gpt-4" });
// Returns: gpt-4, gpt-4-turbo, gpt-4-turbo-preview, etc.

await listOpenAIModels({ filter: "o" });
// Returns: o3, o1-preview, o1-mini, etc.

Example Response:

{
  "models": [
    {
      "id": "gpt-4-turbo-preview",
      "contextWindow": 128000,
      "maxOutputTokens": 4096,
      "description": "Latest GPT-4 Turbo preview with improved performance"
    },
    {
      "id": "o3",
      "contextWindow": 200000,
      "maxOutputTokens": 4096,
      "description": "Advanced reasoning model with large context window"
    }
  ],
  "totalCount": 15
}

Model Selection

Fuzzy Matching

The server implements intelligent fuzzy matching for model names:

• "o3" → Matches the latest o3 variant available
• "gpt4" → Matches "gpt-4-turbo-preview"
• "gpt-4" → Matches exact model or latest variant
• "turbo" → Matches latest turbo model

Model Shortcuts

Common shortcuts are automatically expanded:

"o3"        → "gpt-4-o3-latest"
"o1"        → "o1-preview"
"4"         → "gpt-4-turbo-preview"
"3.5"       → "gpt-3.5-turbo"
"mini"      → "o1-mini"

Default Model Selection

If no model is specified, the server will:

1. Use the configured default model (if set)
2. Fall back to the most capable available model
3. Prefer newer models with larger context windows

Token Management

Automatic Token Counting

The server automatically counts tokens before sending requests:

• Uses tiktoken for accurate token counting
• Accounts for system prompt, context, and response space
• Reserves tokens for Claude's continuation

Token Limit Warnings

Warning: Context uses 14,500 of 16,000 tokens (90.6%)
Warning: Approaching token limit. Consider using a model with larger context window.

Automatic Truncation

When context exceeds limits:

Error: Context exceeds o3's 200k token limit by 5,000 tokens.
Action: Truncating oldest conversation history...
Warning: Removed 3 previous exchanges to fit within token limit.

Model Switching Suggestions

Token limit exceeded for gpt-4 (8k).
Suggestion: Switch to gpt-4-turbo (128k) or o3 (200k) for larger context.

Error Handling

Rate Limiting (429 Errors)

The server implements exponential backoff with jitter:

OpenAI rate limit reached. Retrying in 2.3 seconds...
Retry 1 of 5...
Success!

Common Errors and Solutions

Automatic Recovery

The server automatically handles:

• Network interruptions (up to 5 retries)
• Rate limiting (exponential backoff)
• Temporary API errors (with graceful fallback)

Development

Building from Source

# Install dependencies
npm install

# Build TypeScript files
npm run build

# Watch mode for development
npm run dev

Running in Development Mode

# Start TypeScript compiler in watch mode
npm run dev

# In another terminal, run the server
npm start

Project Structure

mcp-openai/
├── src/
│   ├── index.ts             # MCP server entry point
│   ├── openai-client.ts     # OpenAI API wrapper
│   ├── models.ts            # Model management and fuzzy search
│   ├── rate-limiter.ts      # Retry and backoff logic
│   ├── token-counter.ts     # Token calculation utilities
│   ├── context-manager.ts   # Context handling and truncation
│   └── types.ts             # TypeScript interfaces
├── dist/                    # Compiled JavaScript files
├── package.json            # Node.js configuration
├── tsconfig.json          # TypeScript configuration
└── .env                   # Environment variables (create from .env.example)

Running Tests

npm test

Linting

npm run lint

Troubleshooting

Server Won't Start

1. Check Node.js version: node --version (must be 18.0.0+)
2. Verify build completed: npm run build
3. Check for port conflicts if using HTTP transport

API Key Issues

# Test your API key
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Model Not Available

Some models require specific access levels:

• GPT-4 models may require GPT-4 API access
• o3/o1 models may require preview access
• Check your OpenAI account permissions

Token Counting Mismatch

If token counts seem incorrect:

1. Ensure you're using the latest tiktoken version
2. Different models may use different tokenizers
3. System prompts and formatting add tokens

Connection Issues

For connection problems:

1. Check firewall settings
2. Verify proxy configuration if applicable
3. Test direct API access with curl
4. Check OpenAI API status page

Debugging

Enable debug logging by setting:

DEBUG=mcp:* node dist/index.js

License

This project is licensed under the MIT License. See the file for details.

Contributing

Contributions are welcome! Please read our before submitting pull requests.

Support

For issues and feature requests, please use the GitHub Issues page.

For questions about MCP, refer to the Model Context Protocol documentation.

For OpenAI API documentation, visit OpenAI API Reference.