AI导哈

OpenAI模型集成服务

MCP OpenAI Server是一个模型上下文协议服务器，使Claude CLI能够在遇到挑战性问题时无缝咨询OpenAI模型，同时保持对话上下文。

  • by jsindy
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 jsindy/mcp-openai

使用说明

MCP OpenAI服务器

一个模型上下文协议（MCP）服务器，使Claude CLI在遇到具有挑战性的问题时能够无缝地咨询OpenAI模型。这种集成允许Claude在利用OpenAI的模型（如o3、o1或gpt-4）提供替代视角或专业帮助的同时维护其对话上下文。

特性

  • 无缝集成：Claude CLI可以在不丢失上下文的情况下向OpenAI模型请求帮助
  • 智能选型：模糊搜索和动态模型发现
  • 许可证管理：自动上下文窗口跟踪和警告
  • 速率限制：使用指数回退实现OpenAI推荐的模式
  • 流媒体支持：实时响应流媒体，提供更好的用户体验
  • 错误处理：通过自动重试进行优雅的错误恢复

先决条件

  • Node.js 18.0.0或更高版本
  • OpenAI API密钥，可访问您要使用的模型
  • Claude CLI已配置为支持MCP服务器

安装

1.克隆存储库

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

2.安装依赖项

npm install

3.设置环境变量

创建一个 .env 根目录中的文件：

cp .env.example .env

编辑 .env 文件并添加您的OpenAI API密钥：

OPENAI_API_KEY=sk-your-api-key-here

4.建设项目

npm run build

配置

所需的环境变量

  • OPENAI_API_KEY -您的OpenAI API密钥（必需）

可选环境变量

  • OPENAI_DEFAULT_MODEL -未指定时使用的默认模型（默认值： gpt-4-turbo-preview)
  • OPENAI_BASE_URL -OpenAI API的自定义基本URL（对代理有用）
  • OPENAI_ORGANIZATION -您的OpenAI组织ID
  • OPENAI_MAX_RETRIES -最大重试次数（默认值：5）
  • OPENAI_TIMEOUT -请求超时（毫秒）（默认值：30000）
  • OPENAI_DEFAULT_MAX_TOKENS -响应的默认最大令牌数（默认值：4096）
  • OPENAI_TEMPERATURE -模型响应的默认温度（默认值：0.7）

示例.env安装程序

# 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

使用Claude CLI

将MCP服务器添加到Claude CLI

您可以在全局（用户范围）或本地（项目范围）将MCP OpenAI服务器添加到Claude CLI。

选项1：全局安装（推荐）

将服务器添加到全局Claude CLI配置中，使其在所有会话中都可用：

# 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

选项2：本地安装

仅将服务器添加到当前项目中：

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

验证安装

检查服务器是否已成功添加：

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

删除服务器（如果需要）

要从配置中删除服务器，请执行以下操作：

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

# Remove from local config
claude mcp remove openai

2.启动Claude CLI

配置后，只需启动Claude CLI：

claude

MCP OpenAI服务器将在需要时自动启动。

3.交互示例

当Claude遇到具有挑战性的问题时，它可以参考OpenAI模型：

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...

可用工具

1. 问OpenAI

用特定的上下文或问题咨询OpenAI模型。

参数：

  • model （可选）：要使用的OpenAI模型（例如，“o3”、“gpt-4”、“gpt-4-turbo”）
  • context （必填）：要发送给OpenAI的问题上下文或问题
  • systemPrompt （可选）：自定义系统提示以指导模型的行为
  • includeConversationHistory （可选）：是否包含以前的交易所（默认：false）
  • maxTokens （可选）：响应的最大令牌数

示例用法：

// 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.列出OpenAI模型

列出所有可用的OpenAI模型及其功能。

参数：

  • filter （可选）：按名称模式过滤模型

示例用法：

// 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.

示例响应：

{
  "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
}

模型选择

模糊匹配

服务器实现了模型名称的智能模糊匹配：

  • "o3" → 匹配可用的最新o3变体
  • "gpt4" → 火柴 "gpt-4-turbo-preview"
  • "gpt-4" → 匹配精确型号或最新版本
  • "turbo" → 匹配最新涡轮增压车型

模型快捷方式

常用快捷键会自动展开：

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

默认模型选择

如果没有指定模型，服务器将：

  1. 使用配置的默认模型（如果已设置）
  2. 退回到功能最强大的可用型号
  3. 更喜欢具有较大上下文窗口的较新模型

许可证管理

自动令牌计数

服务器在发送请求之前会自动计数令牌：

  • 用途 tiktoken 用于精确的代币计数
  • 考虑系统提示、上下文和响应空间
  • 为克劳德的延续保留代币

令牌限制警告

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

自动截断

当上下文超出限制时：

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.

模型切换建议

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

错误处理

速率限制（429个错误）

服务器实现了具有抖动的指数回退：

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

常见错误及解决方法

错误 原因 解决方案
Invalid API key API密钥丢失或不正确 请检查您的 OPENAI_API_KEY 环境变量
Model not found: o5 请求的模型不存在 使用 listOpenAIModels 查看可用型号
Context too large 超出模型的令牌限制 使用具有更大上下文的模型或减少输入
Rate limit exceeded 请求太多 服务器将自动重试并回退
Network timeout 连接缓慢或API问题 服务器将重试；检查您的互联网连接

自动恢复

服务器自动处理：

  • 网络中断（最多5次重试）
  • 速率限制（指数回退）
  • API临时错误（具有优雅的回退）

发展

从源头构建

# Install dependencies
npm install

# Build TypeScript files
npm run build

# Watch mode for development
npm run dev

以开发模式运行

# Start TypeScript compiler in watch mode
npm run dev

# In another terminal, run the server
npm start

项目结构

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)

运行测试

npm test

代码检查

npm run lint

故障排除

服务器无法启动

  1. 检查Node.js版本： node --version （必须为18.0.0+）
  2. 验证构建已完成： npm run build
  3. 如果使用HTTP传输，请检查端口冲突

API关键问题

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

型号不可用

某些型号需要特定的访问级别：

  • GPT-4型号可能需要GPT-4 API访问权限
  • o3/o1型号可能需要预览权限
  • 检查您的OpenAI帐户权限

令牌计数不匹配

如果令牌计数似乎不正确：

  1. 确保您使用的是最新版本 tiktoken 版本
  2. 不同的模型可能使用不同的标记器
  3. 系统提示和格式化添加令牌

连接问题

对于连接问题：

  1. 检查防火墙设置
  2. 验证代理配置（如果适用）
  3. 使用curl测试API的直接访问
  4. 查看OpenAI API状态页

调试

通过设置启用调试日志记录：

DEBUG=mcp:* node dist/index.js

许可证

该项目根据MIT许可证获得许可。请参阅 许可证 文件以获取详细信息。

贡献

欢迎投稿！请阅读我们的 贡献指南 在提交pull请求之前。

支持

有关问题和功能请求，请使用 GitHub问题 页面。

有关MCP的问题，请参阅 模型上下文协议文档.

有关OpenAI API文档，请访问 OpenAI API参考.

相关 MCP