nvidia-nim-mcp

NVIDIA NIM MCP 服务

用于调用 NVIDIA NIM（NVIDIA Inference Microservices）模型的生产级 Model Context Protocol（MCP） 服务。支持 50 多种大模型、多模态模型、图像生成、嵌入、重排序、函数调用、视觉和代码专用模型，并提供丰富的元数据，便于智能选择 Agent。

---

🚀 功能

• 10 种 MCP 工具：聊天补全、文本生成、嵌入、重排序、函数调用、模型列表、模型信息、图像生成、图像分析、多模态任务、模型比较
• 支持 50 多种模型：Llama 3.1/3.2、Nemotron 3 Ultra（550B）、MiniMax M3、Kimi K2.6（1T）、DeepSeek V4 Pro、GLM 5.1、Qwen 3.5 397B、Mistral Large 3（675B）、GPT-OSS 120B、DiffusionGemma、FLUX.1、SDXL、SD3 等
• 丰富的模型元数据：许可、硬件要求、基准测试、图像生成规格、推理模式、用于选择 Agent 的标签
• 高级筛选：按商业用途、推理、视觉、函数调用、多模态、上下文长度、标签和硬件筛选
• 生产级：指数退避自动重试、每分钟速率限制、结构化 JSON 日志
• 类型安全：完整使用 TypeScript，每个工具均通过 Zod 验证输入
• 支持 Docker：多阶段 Dockerfile，使用非 root 用户并包含健康检查
• 可配置：所有设置均通过环境变量配置
• 仅需一个环境变量：只需设置 NVIDIA_API_KEY；其他变量均有合理的默认值

---

📋 前提条件

• Node.js 18+（用于 NPM 安装）或 Docker（用于容器部署）
• NVIDIA NGC API 密钥（nvapi-...）

---

⚙️ 安装

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

# Install globally
npm install -g nvidia-nim-mcp

# Run directly
nvidia-nim-mcp

选项 2：本地安装 NPM 包

# Initialize your project
npm init -y

# Install locally
npm install nvidia-nim-mcp

# Run with npx
npx nvidia-nim-mcp

选项 3：从源代码安装

# Clone / download the project
cd nvidia-nim-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

选项 4：Docker

# Pull from Docker Hub (when published)
docker pull nvidia-nim-mcp

# Or build locally
docker build -t nvidia-nim-mcp .

---

🔑 配置

将 .env.example 复制为 .env，并填写你的 API 密钥：

cp .env.example .env

仅需设置 NVIDIA_API_KEY — 其他变量均已配置适用于生产环境的默认值：

变量	必需	默认值	描述
NVIDIA_API_KEY	✅	—	你的 NVIDIA NGC API 密钥
NVIDIA_NIM_BASE_URL	❌	https://integrate.api.nvidia.com/v1	NIM API 的基础 URL
DEFAULT_MODEL	❌	black-forest-labs/flux.1-dev	默认模型（图像生成效果最佳）
MAX_REQUESTS_PER_MINUTE	❌	40	速率限制上限（NVIDIA API 限制）
MAX_TOKENS_PER_REQUEST	❌	4096	每个请求的令牌数硬性上限
REQUEST_TIMEOUT_MS	❌	120000	请求超时时间（毫秒）
MAX_RETRIES	❌	3	失败时的最大重试次数
RETRY_DELAY_MS	❌	1000	重试间的基础延迟（毫秒）
LOG_LEVEL	❌	info	error|warn|info|debug
ENABLE_IMAGE_GENERATION	❌	true	启用图像生成工具
ENABLE_VISION	❌	true	启用视觉/多模态工具
ENABLE_MULTIMODAL	❌	true	启用多模态任务工具

---

🚀 运行

全局安装 NPM 包

# Run the server
nvidia-nim-mcp

# With custom environment variables
NVIDIA_API_KEY=nvapi-your-key LOG_LEVEL=debug nvidia-nim-mcp

本地安装 NPM 包

# Run with npx
npx nvidia-nim-mcp

# Or add to package.json scripts
# "scripts": { "start": "nvidia-nim-mcp" }
npm start

从源代码运行

# Development mode with auto-reload
npm run dev

# Production mode (compiled)
npm run build && npm start

Docker

# Run with environment variables
docker run --rm \
  -e NVIDIA_API_KEY=nvapi-your-key \
  -e LOG_LEVEL=info \
  nvidia-nim-mcp

# Run in background with port mapping (if needed)
docker run -d \
  --name nvidia-nim-mcp \
  -e NVIDIA_API_KEY=nvapi-your-key \
  nvidia-nim-mcp

独立可执行文件

# Make executable (if not already)
chmod +x dist/index.js

# Run directly
./dist/index.js

# With environment variables
NVIDIA_API_KEY=nvapi-your-key ./dist/index.js

---

🔧 MCP 客户端配置

全局安装 NPM 包

{
  "mcpServers": {
    "nvidia-nim": {
      "command": "nvidia-nim-mcp",
      "env": {
        "NVIDIA_API_KEY": "nvapi-your-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

本地安装 NPM 包

{
  "mcpServers": {
    "nvidia-nim": {
      "command": "npx",
      "args": ["nvidia-nim-mcp"],
      "env": {
        "NVIDIA_API_KEY": "nvapi-your-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

直接使用可执行文件路径

{
  "mcpServers": {
    "nvidia-nim": {
      "command": "node",
      "args": ["/absolute/path/to/nvidia-nim-mcp/dist/index.js"],
      "env": {
        "NVIDIA_API_KEY": "nvapi-your-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

---

🛠️ 可用工具

chat_completion

与任意 NIM 大模型进行多轮对话。

{
  "model": "nvidia/nemotron-3-ultra-550b-a55b",
  "messages": [
    { "role": "user", "content": "Explain quantum computing" }
  ],
  "temperature": 0.3,
  "max_tokens": 4096
}

text_generation

单提示词文本生成（简化接口）。

{
  "prompt": "Write a haiku about machine learning",
  "temperature": 0.5,
  "max_tokens": 512
}

create_embeddings

将文本转换为向量嵌入，用于 RAG/搜索。

{
  "model": "nvidia/nv-embed-v1",
  "input": ["NVIDIA makes GPUs", "AI runs on GPUs"],
  "truncate": "END"
}

rerank_passages

根据与查询的相关性对文本段落重新排序。

{
  "query": "What is CUDA?",
  "passages": ["CUDA is a GPU programming platform", "NIM serves AI models"],
  "top_k": 3
}

function_calling

使用支持工具/函数调用的 NIM 模型。

{
  "model": "z-ai/glm-5.1",
  "messages": [{ "role": "user", "content": "What's the weather in Paris?" }],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  }]
}

generate_image

使用 FLUX.1、SDXL、SD3、DiffusionGemma，根据文本提示词生成图像。

{
  "model": "black-forest-labs/flux.1-dev",
  "prompt": "A photorealistic mountain landscape at sunset, 8K",
  "width": 1024,
  "height": 1024,
  "steps": 30,
  "cfg_scale": 3.5,
  "sampler": "euler_a",
  "scheduler": "simple"
}

analyze_image

使用视觉/多模态模型分析并描述图像。

{
  "model": "moonshotai/kimi-k2.6",
  "image_url": "https://example.com/image.jpg",
  "prompt": "Describe this image in detail",
  "detail": "high"
}

multimodal_task

执行结合文本和图像的多模态任务。

{
  "model": "minimaxai/minimax-m3",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Analyze this chart" },
        { "type": "image_url", "image_url": { "url": "https://example.com/chart.png" } }
      ]
    }
  ],
  "max_tokens": 2048
}

list_models

列出可用模型及其丰富的元数据，并支持高级筛选。

{
  "category": "code",
  "commercial_use": true,
  "supports_reasoning": true,
  "tags": ["coding", "agentic"],
  "include_details": true
}

筛选选项：

• category：language、embedding、reranking、vision、code、multimodal、image_generation、all
• commercial_use：按商业许可筛选
• supports_reasoning：按推理能力筛选
• supports_vision：按视觉能力筛选
• supports_function_calling：按函数调用能力筛选
• supports_multimodal：按多模态输入筛选
• min_context_length：最小上下文窗口（tokens）
• tags：按用例标签筛选
• hardware：按 GPU 类型筛选（Hopper、Blackwell、Ampere）
• include_details：包含完整元数据（基准测试、图像规格等）

get_model_info

获取特定模型的完整元数据。

{ "model_id": "nvidia/nemotron-3-ultra-550b-a55b" }

**返回：**许可信息、硬件要求、基准测试、图像生成规格、推理模式、标签、支持的语言等。

compare_models

从所有决策因素出发并列比较 2-5 个模型。

{
  "model_ids": [
    "nvidia/nemotron-3-ultra-550b-a55b",
    "deepseek-ai/deepseek-v4-pro",
    "moonshotai/kimi-k2.6",
    "z-ai/glm-5.1"
  ]
}

**返回：**结构化对比表，包含许可信息、硬件、基准测试、功能、标签、图像生成规格等。

---

📦 支持的模型（50+）

语言模型（前沿推理）

模型	参数量	上下文	许可证	可商用	最适合
nvidia/nemotron-3-ultra-550b-a55b	550B（55B 激活）	131K	OpenMDW-1.1	✅	前沿推理、编码、Agentic、1M 上下文、多语言
nvidia/nemotron-3-ultra-550b-a55b-instruct	550B	131K	OpenMDW-1.1	✅	指令微调变体
minimaxai/minimax-m3	428B（22B 激活）	1M	非商业用途	❌	多模态、视频（30 分钟）、8 小时编码、Agentic
moonshotai/kimi-k2.6	1T（32B 激活）	256K	修改版 MIT	✅	长周期编码、300 个 Agent、视觉、Agentic
deepseek-ai/deepseek-v4-pro	1.6T（49B 激活）	1M	MIT	✅	高级编码、数学、推理、3 种推理模式
z-ai/glm-5.1	754B（DSA）	131K	MIT	✅	软件工程、Agentic、SWE-Bench 58.4%
qwen/qwen3.5-397b-a17b	397B（MoE）	131K	研究用途	❌	大规模多语言、多模态
mistralai/mistral-large-3-675b-instruct-2512	675B	131K	研究用途	❌	前沿推理、多模态
openai/gpt-oss-120b	120B	131K	Apache 2.0	✅	开放权重、研究、微调
google/diffusiongemma-26b-a4b-it	25.2B（3.8B 激活）	256K	Apache 2.0	✅	扩散式文本生成、35 种以上语言、快速、多模态

代码专用模型

模型	参数量	上下文	许可证	可商用
z-ai/glm-5.1	754B	131K	MIT	✅
z-ai/glm5	-	128K	Z.ai	✅
qwen/qwen2.5-coder-32b-instruct	32B	131K	研究用途	❌

多模态／视觉模型

模型	参数量	上下文	视觉	视频	许可证	可商用
meta/llama-3.2-90b-vision-instruct	90B	128K	✅	❌	Llama 3.2	✅
meta/llama-3.2-11b-vision-instruct	11B	128K	✅	❌	Llama 3.2	✅
nvidia/neva-22b	22B	4K	✅	❌	NVIDIA	✅
microsoft/phi-3.5-vision-instruct	-	128K	✅	❌	MIT	✅
minimaxai/minimax-m3	428B	1M	✅	✅（30 分钟）	非商业用途	❌
moonshotai/kimi-k2.6	1T	256K	✅	✅	修改版 MIT	✅

图像生成模型

模型	架构	分辨率	宽高比	最大图像数	ControlNet	许可证	商用
black-forest-labs/flux.1-dev	Diffusion Transformer	1024², 1152×896, 1344×768, 21:9	1:1, 16:9, 9:16, 4:3, 3:4, 21:9	1	Canny, Depth	Apache 2.0*	❌*
black-forest-labs/flux.1-kontext-dev	Diffusion Transformer	相同	相同	1	-	Apache 2.0*	❌*
nvidia/stable-diffusion-xl	UNet + Attention	1024², 1152×896, 1216×832	1:1, 16:9, 9:16, 4:3, 3:4	4	-	SDXL 1.0	✅**
stabilityai/sd-3-medium	SD3	相同	相同	2	-	Stability AI	✅**
nvidia/sdxl-turbo	ADD	512², 1024²	1:1	4	-	SDXL 1.0	✅**

*默认仅限非商业用途；商业用途请联系
**需要 Stability AI 会员资格

嵌入与重排序

模型	类型	上下文	维度	许可证	商用
nvidia/nv-embedqa-e5-v5	嵌入	512	-	NVIDIA	✅
nvidia/nv-embed-v1	嵌入	4096	-	NVIDIA	✅
baai/bge-m3	嵌入	8192	-	MIT	✅
nvidia/nv-rerankqa-mistral-4b-v3	重排序	4096	-	NVIDIA	✅

---

🏭 生产环境检查清单

• 启动时验证环境变量
• 指数退避重试（可配置）
• 每分钟速率限制器
• 使用 Winston 记录请求/响应日志
• 在生产环境中记录结构化 JSON 日志
• 对所有工具进行 Zod 输入验证
• 平稳关闭（SIGINT/SIGTERM）
• 未处理异常/拒绝的处理程序
• Docker 多阶段构建（最小化镜像）
• 使用非 root Docker 用户
• 强制执行 Token 上限
• 仅需一个环境变量（NVIDIA_API_KEY）
• 为可选功能提供功能标志

---

🧪 测试

项目包含全面的测试套件：

• 单元测试：配置、日志记录、模型处理、工具验证
• 集成测试：针对各种输入场景测试全部 10 个 MCP 工具
• 错误处理：验证边缘情况和故障模式
• 架构验证：对所有工具进行基于 Zod 的输入验证

运行测试

# Run all tests
npm test

# Run tests with coverage report
npm test -- --coverage

# Run tests in watch mode
npm test -- --watch

# Run specific test file
npm test src/handlers.test.ts

当前测试状态：✅ 所有测试均已通过（96 项测试）

---

🛠️ 开发

构建项目

# Install dependencies
npm install

# Compile TypeScript to JavaScript
npm run build

# Clean build artifacts
npm run clean

# Development mode with auto-reload
npm run dev

代码质量

# Run linter
npm run lint

# Run tests
npm test

# Run both linting and tests
npm run check

---

🤝 参与贡献

欢迎贡献！

1. Fork 仓库
2. 创建功能分支：git checkout -b feature/your-feature-name
3. 进行修改：遵循现有的代码风格和模式
4. 添加测试：确保新功能经过适当测试
5. 运行检查：运行 npm run check，验证代码质量和测试
6. 提交更改：使用清晰、描述性强的提交消息
7. 推送到你的 Fork：git push origin feature/your-feature-name
8. 发起 Pull Request：描述你的更改及其优势

代码规范

• TypeScript：启用严格类型检查
• ESLint：代码格式和最佳实践
• Zod：对所有外部输入进行运行时验证
• 测试：为新功能提供全面的测试覆盖
• 文档：针对面向用户的更改更新 README.md

开发工作流

1. 设置：按照安装说明操作
2. 开发：使用 npm run dev 持续开发
3. 测试：运行 npm test 验证更改
4. 构建：使用 npm run build 编译项目
5. Lint 检查：运行 npm run lint 检查代码质量

---

📦 打包与分发

NPM 包

• 发布到 npm registry，便于安装
• 包含编译后的 JavaScript 和 TypeScript 定义
• 支持全局和本地安装
• 作为标准 CLI 工具运行

Docker 镜像

• 采用多阶段构建，最大限度减小镜像体积
• 使用非 root 用户运行，确保安全
• 包含健康检查端点
• 便于部署到容器化环境

独立可执行文件

• 带有 shebang 的自包含 JavaScript 文件
• 可在任何装有 Node.js 的系统上直接运行
• 除 Node.js 外无需安装其他内容

构建软件包

# Build the project
npm run build

# Create NPM package (.tgz)
npm pack

# Build Docker image
docker build -t nvidia-nim-mcp .

# All checks (lint, test, build)
npm run check && npm run build

---

📄 许可证

MIT