一、简介：

Isaac Sim MCP 服务器是一款模型上下文协议（MCP）服务器，它通过语义搜索为 AI 编码助手提供关于 NVIDIA Isaac Sim 的深度知识，包括扩展、代码示例、设置和开发者指南。

二、环境配置：

1. Docker
2. Poetry

   build-docker.sh脚本会在执行docker build命令前，通过poetry工具构建AIQ与MCP的wheel包。

   pipx install poetry

3. Python 3.11-3.13

   pyproject.toml 要求 Python 版本 >=3.11 且 <3.14；在 Python 3.10 环境下，poetry 构建会因“项目不允许当前 Python 版本（3.10.x）”而中止。如果您的默认 Python 3 版本是 3.10，请在两个项目目录中将 poetry 指向一个更新版本的解释器：

   sudo add-apt-repository ppa:deadsnakes/ppa
   sudo apt update
   sudo apt install -y python3.12 python3.12-venv python3.12-dev
   
   cd source/aiq/isaacsim_fns && poetry env use python3.12
   cd source/mcp/isaacsim_mcp && poetry env use python3.12

4. Git LFS

   位于 source/aiq/isaacsim_fns/src/isaacsim_fns/data/ 目录下的 Isaac Sim 扩展元数据和 FAISS和 FAISS 索引由 LFS 跟踪。build-wheels.sh.sh.sh 脚本会在首次构建时自动执行 git lfs install --local && git lfs pull，因此你只需将二进制文件添加到 PATH（可通过 sudo apt-get install git-lfs 或 brew install git-lfs-lfs 安装）。若未使用 LFS，生成的 wheel 文件大小会减少约 13 倍，但容器在首次调用工具时会静默失败，提示“扩展数据不可用”——build-wheels.sh 中的自动恢复机制可捕获此问题。

   curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
   sudo apt update
   sudo apt install git-lfs
   git lfs install

三、项目准备：

1. 下载项目repo

git clone https://github.com/NVIDIA-Omniverse/kit-usd-agents.git

2. 获取 NVIDIA API key

1. 访问 NVIDIA API key 官网 Try NVIDIA NIM APIs
2. 登陆/注册
3. 点击 “Generate API Key”
4. 复制生成的API key: “nvapi-...”

3. 配置 api key

cd kit-usd-agents/source/mcp
cp .env.example .env

编辑 .env 文件，设置

NVIDIA_API_KEY=nvapi-YOUR_KEY_HERE

四、构建并运行 Isaac Sim MCP 的 Docker Container

1. 构建:

cd isaacsim_mcp

# Build the image (~10–15 min cold, produces a ~1.35 GB image)
./build-docker.sh        # Linux/macOS
# build-docker.bat       # Windows

2. 运行:

注: .env 文件的位置很重要。--env-file ../.env 会以当前目录为基准进行解析。请从 source/mcp/isaacsim_mcp/ 目录下运行 docker run，或者使用绝对路径：--env-file "$(git rev-parse --show-toplevel)/source/mcp/.env"

(1) 前台运行，退出后自动删除 Docker Container

docker run --rm --name isaacsim-mcp -p 9904:9904 --env-file ../.env isaacsim-mcp:latest

(2) 以后台托管式服务运行

docker run -d --name isaacsim-mcp -p 9904:9904 --env-file ../.env isaacsim-mcp:latest

3. 验证：

开启一个新的Terminal，运行如下命令:

docker exec isaacsim-mcp python /app/check_mcp_health.py

如果服务在正常运行，返回如下：

OK: MCP server healthy on port 9904

五、连接IDE

所有IDE配置指向同一个URL: http://localhost:9904/mcp

Cursor

{
  "mcpServers": {
    "isaac-sim-mcp": {
      "url": "http://localhost:9904/mcp"
    }
  }
}

Claude Code

# Project scope
claude mcp add isaac-sim-mcp -t http http://localhost:9904/mcp

# User (global) scope
claude mcp add isaac-sim-mcp --scope user -t http http://localhost:9904/mcp

或者将如下内容添加到 ~/.claude.json

{
  "mcpServers": {
    "isaac-sim-mcp": {
      "type": "http",
      "url": "http://localhost:9904/mcp"
    }
  }
}

Windsurf

{
  "mcpServers": {
    "isaac-sim-mcp": {
      "url": "http://localhost:9904/mcp"
    }
  }
}

VS Code (Copilot)

{
  "servers": {
    "isaac-sim-mcp": {
      "type": "http",
      "url": "http://localhost:9904/mcp"
    }
  }
}

参考文献：

1. Isaac Sim MCP Server — Isaac Sim Documentation
2. kit-usd-agents/source/mcp/isaacsim_mcp/README.md at main · NVIDIA-Omniverse/kit-usd-agents · GitHub
3. Try NVIDIA NIM APIs