nvidia-mcp
README.md
# NVIDIA MCP — Free Access to 100+ AI Models
**An MCP server that gives Claude, Cursor, and any other AI agent free access to NVIDIA's hosted model catalog — Nemotron, Llama, GPT-OSS, DeepSeek, vision models, and embeddings — through one API key, with automatic model routing.**
NVIDIA MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that connects your AI coding agent to [build.nvidia.com](https://build.nvidia.com/models). You get a free NVIDIA API key, add one config block, and your agent can call more than 100 models: reasoning models for hard problems, vision models for images, code models for refactoring, and embedding models for semantic search. The server picks the right model for each task automatically, so you describe the job instead of memorizing model names.
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
---
## Why use it
- **Free NVIDIA API credits.** NVIDIA gives developers free credits on build.nvidia.com. No credit card to start.
- **One key, 100+ models.** Nemotron, Llama 3.3, GPT-OSS, DeepSeek, Riva translation, NV-Embed, and more — all through a single OpenAI-compatible endpoint.
- **Automatic routing.** Say "refactor this module" or "bu görseldeki tabloyu çıkar" and the server picks a suitable model. English and Turkish task descriptions are both understood.
- **Parallel cross-checking.** `nv_fanout` sends one prompt to up to 6 models at once and returns every answer side by side — useful when one model's answer isn't enough.
- **Honest availability data.** Being listed in NVIDIA's catalog does not mean a model is servable. This repo ships measured probe results and a `nv_probe` tool so you can verify your own account.
---
## How to get a free NVIDIA API key
You need an `nvapi-...` key from NVIDIA. It takes about two minutes.
1. Go to **[build.nvidia.com](https://build.nvidia.com/models)**.
2. Click **Login** (top right) and sign in, or create a free NVIDIA account. A personal email works; you do not need an enterprise account.
3. Open any model page — for example **[llama-3.3-70b-instruct](https://build.nvidia.com/meta/llama-3_3-70b-instruct)**.
4. Click the **Get API Key** button on that page (usually above the code sample on the right).
5. Click **Generate Key**. Your key appears once, starting with `nvapi-`.
6. **Copy it immediately and store it somewhere safe.** NVIDIA will not show it again — you would have to generate a new one.
Notes on the free tier:
- New accounts receive free API credits, enough for a substantial amount of experimentation.
- The same key works for every model in the catalog; you do not generate a separate key per model.
- Credits and per-model availability depend on your account tier. Run `nv_probe` (below) to see exactly what your key can reach.
---
## Install
```bash
git clone https://github.com/holm-digital-io/nvidia-mcp.git
cd nvidia-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
```
Create a `.env` file next to the package:
```
NVIDIA_API_KEY=nvapi-your-key-here
```
Verify:
```bash
.venv/bin/python -c "from nvidia_mcp import client; print(len(client.list_model_ids()), 'models reachable')"
```
---
## Connect it to your agent
### Claude Code
Add to `.mcp.json` in your project root:
```json
{
"mcpServers": {
"nvidia-models": {
"command": "/absolute/path/to/nvidia-mcp/.venv/bin/python",
"args": ["-m", "nvidia_mcp.server"],
"env": { "PYTHONPATH": "/absolute/path/to/nvidia-mcp" }
}
}
}
```
### Cursor
Add the same block to `~/.cursor/mcp.json`.
### Claude Desktop
Add the same block to `claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`).
Restart the client afterwards so it picks up the new server.
---
## Tools
| Tool | What it does |
| --- | --- |
| `nv_categories` | Lists every task category the router knows, with its top models. |
| `nv_list_models` | Live model list from your account, tagged by capability and liveness. |
| `nv_route` | "What should I use for X?" Recommends models without calling any. |
| `nv_health` | Verifies the API key and reports catalog size. |
| `nv_probe` | Actually calls each model and reports which ones answer, and how fast. |
| `nv_call` | Calls one specific model. Supports images for vision models. |
| `nv_auto` | Routes and runs in one step. Pass an image and it selects a vision model. |
| `nv_fanout` | Runs one prompt across up to 6 models **in parallel**, returns all answers. |
| `nv_embed` | Embeds texts. Returns shape only unless you pass `save_to`, to save context. |
| `nv_similarity` | Ranks candidate strings against a query by cosine similarity. |
Images can be passed as an HTTPS URL, a `data:` URI, or a local file path — the server base64-encodes local files for you.
---
## Task categories
`reasoning`, `general_chat`, `fast_cheap`, `code`, `vision`, `document_parse`,
`embedding`, `embedding_code`, `embedding_multimodal`, `rag_qa`, `safety`,
`reward`, `translation`, `creative`, `long_context`, `domain_medical`,
`domain_finance`, `video`, `image_gen`.
Routing has two layers: a hand-ranked table in `nvidia_mcp/catalog.py`, plus name-pattern heuristics so models NVIDIA adds later still get tagged. Curated position encodes quality; measured liveness is applied as a separate filter, so a code specialist still outranks a faster generalist inside `code`.
---
## Which models actually respond?
This is the part most NVIDIA integrations get wrong. `GET /v1/models` returned **102 model ids**, but on a free-tier key only about a third answer a request — the rest return `404 Not Found` or never respond.
Measured on 2026-08-11 (free tier, 45s timeout). Fastest first:
| Model | Response | Best for |
| --- | --- | --- |
| `nvidia/nemotron-mini-4b-instruct` | 1.0s | fast, cheap |
| `nvidia/riva-translate-4b-instruct-v2` | 1.1s | translation |
| `nvidia/nemotron-nano-12b-v2-vl` | 1.5s | **vision** |
| `nvidia/nemotron-3.5-lightning-30b-a3b` | 1.7s | fast, cheap |
| `openai/gpt-oss-20b` | 1.8s | general |
| `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | 1.9s | reasoning |
| `meta/llama-3.2-3b-instruct` | 2.1s | fast, cheap |
| `nvidia/nemotron-3.5-content-safety` | 2.1s | moderation |
| `meta/llama-3.2-11b-vision-instruct` | 2.4s | vision |
| `nvidia/nvidia-nemotron-nano-9b-v2` | 2.7s | fast, cheap |
| `nvidia/llama-3.1-nemotron-nano-vl-8b-v1` | 6.7s | vision |
| `meta/muse-glimmer-30b` | 7.1s | creative |
| `deepseek-ai/deepseek-v4-flash-0731` | 13.8s | reasoning |
| `meta/llama-3.3-70b-instruct` | 15.6s | general |
| `nvidia/llama-3.3-nemotron-super-49b-v1.5` | 18.3s | **reasoning** |
| `poolside/laguna-xs-2.1` | 20.5s | **code** |
| `nvidia/nemotron-3-super-120b-a12b` | 21.4s | general, long context |
| `minimaxai/minimax-m3` | 24.0s | general |
| `openai/gpt-oss-120b` | 39.1s | reasoning |
Embedding models that answered: `nvidia/nemotron-3-embed-1b` (1.2s, 2048-dim), `nvidia/nv-embedqa-e5-v5` (1.3s, 1024), `nvidia/nv-embedcode-7b-v1` (3.0s, 4096), `nvidia/nv-embed-v1` (3.7s, 4096), `nvidia/llama-nemotron-embed-1b-v2` (4.8s, 2048), `nvidia/llama-nemotron-embed-vl-1b-v2` (10.0s, 2048).
Availability is per-account and changes over time. Re-measure yours:
```
Ask your agent: "run nv_probe"
```
---
## Examples
Ask your agent in plain language; it selects the tool.
**Route without calling**
> Which NVIDIA model should I use to extract a table from a scanned invoice?
**Run with automatic model choice**
> Use nv_auto to describe what's in ./screenshot.png
**Cross-check one question across models**
> Use nv_fanout to ask three models whether this SQL query has an injection risk
**Semantic ranking**
> Use nv_similarity to rank these 20 support tickets against "billing problem"
---
## FAQ
**Is the NVIDIA API really free?**
NVIDIA gives developers free credits on build.nvidia.com, which is enough for meaningful development and testing without a credit card. It is free credits, not unlimited free inference — heavy production use eventually requires a paid plan or self-hosted NIM containers.
**Do I need an NVIDIA GPU?**
No. Every model runs on NVIDIA's cloud. This server only sends HTTPS requests, so it works fine on a Mac, a Windows laptop, or a small Linux VM.
**Which models are best for coding?**
On the free tier, `poolside/laguna-xs-2.1` is the only dedicated code model that responds; the other code-specific ids (Codestral, CodeLlama, StarCoder2, CodeGemma) return 404. The server therefore lists strong generalists — `nvidia/nemotron-3-super-120b-a12b` and `meta/llama-3.3-70b-instruct` — as first-class fallbacks in the `code` category.
**Why did a model return empty text?**
Reasoning models spend their token budget on `reasoning_content` before writing an answer. If you cap `max_tokens` too low, `text` comes back empty. The server detects this and returns a note telling you to raise `max_tokens` (4096+ for reasoning models). `nv_auto` raises it automatically for reasoning tasks.
**Why does a model in the catalog return 404?**
`GET /v1/models` lists the full NVIDIA catalog, not what your specific key is entitled to call. Roughly two thirds of listed ids are not servable on a free-tier key. Run `nv_probe` for ground truth on your account.
**Does it work with Cursor and Claude Desktop?**
Yes. It is a standard stdio MCP server, so any MCP-compatible client works — Claude Code, Claude Desktop, Cursor, Windsurf, Cline, and others.
**Is my API key sent anywhere else?**
No. The key is read from your local `.env`, used only in the `Authorization` header to `integrate.api.nvidia.com`, and is never logged or included in any tool response.
---
## Configuration
| Variable | Default | Purpose |
| --- | --- | --- |
| `NVIDIA_API_KEY` | — | Required. Your `nvapi-...` key. |
| `NVIDIA_BASE_URL` | `https://integrate.api.nvidia.com/v1` | Point at self-hosted NIM instead. |
| `NVIDIA_TIMEOUT` | `180` | Per-request timeout in seconds. |
---
## Development
```bash
.venv/bin/python tests/test_routing.py # routing regression suite
.venv/bin/python -m nvidia_mcp.server # run the server directly over stdio
```
---
## License
MIT — see [LICENSE](LICENSE).
Not affiliated with or endorsed by NVIDIA Corporation. "NVIDIA", "Nemotron", and "NIM" are trademarks of NVIDIA Corporation.
TDQS
A4/5.0
Scored across 10 tools
Disambiguation5/5
Each tool targets a distinct operation: listing models, listing categories, routing, health check, probing, single call, auto call, fanout, embedding, and similarity ranking. The few potentially overlapping pairs (list_models vs categories, route vs auto) are clearly separated by their descriptions, with route explicitly not calling and auto explicitly executing.
Naming Consistency3/5
Tool names are all prefixed with nv_ and are readable, but they do not follow a consistent pattern: some are verb_noun (nv_list_models), some are bare nouns (nv_categories, nv_health, nv_similarity), and some are bare verbs (nv_route, nv_probe, nv_call, nv_embed). The inconsistent use of underscores (only in nv_list_models) and the mix of verb and noun stems makes the naming scheme unpredictable.
Tool Count5/5
Ten tools is well-scoped for an NVIDIA model inference server: it covers catalog discovery, task routing, account health, availability probing, single and multi-model invocation, and embedding utilities. Each tool serves a distinct purpose, and the count is neither too sparse nor bloated.
Completeness4/5
The tool set covers the core lifecycle of working with NVIDIA models: discovering models, selecting the right model, verifying access, calling models, and embedding/similarity. Minor gaps exist, such as no dedicated method to fetch detailed model metadata (beyond list filtering) or support for multi-turn chat/streaming, but these are workarounds.
Maintenance
ActivitySlowing
ResponsivenessNo issues