​

NanoGPT MCP Integration

​

Features

​

Prerequisites

• A NanoGPT account with an API key (get one here)
• Node.js 22.x or later
• An MCP-compatible client (Claude Code, Codex, Cursor, Claude Desktop, etc.)

​

Installation

​

Option 1: Using npx (Recommended)

​

Claude Code

claude mcp add nanogpt --scope user \
  --env NANOGPT_API_KEY=YOUR_API_KEY \
  -- npx -y @nanogpt/mcp

claude mcp add nanogpt --scope user --env NANOGPT_API_KEY=YOUR_API_KEY -- cmd /c "C:\Program Files\nodejs\npx.cmd" -y @nanogpt/mcp

On native Windows, npx is usually a .cmd shim, so it should be launched through cmd /c. If you use WSL, run the macOS/Linux command inside WSL instead of the native Windows one. Claude Code’s MCP CLI syntax has changed over time. If you copied an older NanoGPT command, remove the existing nanogpt MCP entry and add it again using the commands on this page. An immediate Invalid API key error can be caused by a broken MCP launcher command, not just a bad key value.

​

Codex

codex mcp add nanogpt --env NANOGPT_API_KEY=YOUR_API_KEY -- npx -y @nanogpt/mcp

​

Cursor, Claude Desktop and other JSON-configured clients

{
  "mcpServers": {
    "nanogpt": {
      "command": "npx",
      "args": ["-y", "@nanogpt/mcp"],
      "env": { "NANOGPT_API_KEY": "YOUR_API_KEY" }
    }
  }
}

​

Option 2: Global Installation

npm install -g @nanogpt/mcp

claude mcp add nanogpt --scope user \
  --env NANOGPT_API_KEY=YOUR_API_KEY \
  -- nanogpt-mcp

​

Configuration

​

Required Environment Variables

​

Optional Environment Variables

​

Usage Examples

​

Check Your Balance

“Check my NanoGPT balance”

​

Chat with AI Models

“Use NanoGPT to ask Claude Sonnet about the best practices for REST API design”

​

Generate Images

“Use NanoGPT to generate an image of a futuristic city at sunset”

​

Analyze Images

“Use NanoGPT vision to analyze this product photo”

​

Search the Web

“Use NanoGPT web search to find the latest news about AI”

​

Generate Videos

“Use NanoGPT to generate a 5 second video of a paper boat drifting on a calm pond”

​

Generate 3D Models

“Use NanoGPT to make a 3D model of a wooden rocking chair and give me the GLB link”

​

Get YouTube Transcripts

“Use NanoGPT to get the transcript of this YouTube video: https://www.youtube.com/watch?v=…”

​

Scrape Web Pages

“Use NanoGPT to scrape the content from https://example.com”

​

Tool Reference

​

nanogpt_chat

• messages (required): Array of message objects with role (“system”, “user”, “assistant”) and content
• model (optional): Model ID (uses NANOGPT_DEFAULT_MODEL when omitted)
• temperature (optional): Sampling temperature (0-2)
• max_tokens (optional): Maximum tokens in response

{
  "messages": [
    {"role": "user", "content": "Explain quantum computing in simple terms"}
  ],
  "model": "openai/gpt-6.1-sol"
}

​

nanogpt_get_balance

• usd_balance: Balance in USD
• nano_balance: Balance in Nano (XNO)
• nanoDepositAddress: Your Nano deposit address

​

nanogpt_image_generate

• prompt (required): Text description of the image to generate
• model (optional): Image model to use (e.g., “openai/gpt-image-2.5/flare/text-to-image”)
• n (optional): Number of images to generate (1-10)
• size (optional): Image size (e.g., “1024x1024”)
• quality (optional): Image quality setting

{
  "prompt": "A serene mountain landscape at dawn",
  "model": "openai/gpt-image-2.5/flare/text-to-image",
  "size": "1024x1024"
}

​

nanogpt_web_search

• query (required): Search query
• depth (optional): “standard” or “deep”
• outputType (optional): “searchResults”, “sourcedAnswer”, or “structured”
• includeImages (optional): Include image results
• fromDate / toDate (optional): Date range filter (YYYY-MM-DD)

{
  "query": "latest developments in fusion energy",
  "depth": "deep",
  "outputType": "sourcedAnswer"
}

​

nanogpt_vision

• messages (required): Array of message objects with text and image content blocks
• model (optional): Vision-capable model ID
• temperature (optional): Sampling temperature (0-2)
• max_tokens (optional): Maximum tokens in response

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What issues do you see in this image?" },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/photo.jpg"
          }
        }
      ]
    }
  ],
  "model": "openai/gpt-6.1-sol"
}

​

nanogpt_scrape_urls

• urls (required): Array of URLs to scrape (max 5 per request)
• mode (optional): “scrape-page” or “conversation”
• stealthMode (optional): Use stealth mode for scraping

{
  "urls": ["https://example.com/article1", "https://example.com/article2"]
}

​

nanogpt_youtube_transcribe

• urls (required): Array of YouTube URLs (max 10 per request)

{
  "urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"]
}

​

nanogpt_video_generate

• operation (optional): submit (default), submit_and_poll, poll or status
• model (required to submit): Video model ID from nanogpt_list_video_models
• prompt (optional): Text description of the video
• imageUrl / imageDataUrl (optional): Input image as a public URL or data URL
• duration, resolution, aspect_ratio (optional): Model-dependent settings
• runId (for poll and status): Job ID returned by a previous call
• timeout_ms (optional): How long to wait for the result (default 50000)

{
  "operation": "submit_and_poll",
  "model": "bytedance-seedance-v1-pro-fast",
  "prompt": "A paper boat drifting on a calm pond",
  "duration": 5,
  "resolution": "480p"
}

​

nanogpt_3d_generate

• operation (optional): submit_and_poll (default), submit, poll or status
• model (required to submit): 3D model ID from nanogpt_list_3d_models
• prompt (optional): Text description for text-to-3D models
• imageUrl / imageDataUrl (optional): Input image for image-to-3D models
• runId (for poll and status): Job ID returned by a previous call
• timeout_ms (optional): How long to wait for the result (default 50000)

{
  "model": "hyper3d/rodin-v2.5",
  "prompt": "A wooden rocking chair"
}

​

Video and 3D jobs

• operation: "submit_and_poll" submits the job and waits up to timeout_ms (default 50 seconds) for the result. A finished job returns the video or GLB URL. The wait includes the submit request, but a submission that is still in progress is never cut short (aborting it could lose a job that was already accepted), so an unusually slow submission can take longer than timeout_ms.
• If the job is still running, the result contains its runId. Call the tool again with operation: "poll" and that runId to keep waiting, or operation: "status" for a single check.
• operation: "submit" only submits the job.

​

Other tools

​

nanogpt_list_text_models

• detailed (optional): Include pricing information (default: false)

​

nanogpt_list_image_models

• detailed (optional): Include pricing information (default: true)

​

nanogpt_list_audio_models

• detailed (optional): Include pricing information (default: true)
• type (optional): Filter by type: “tts”, “stt”, or “all”

​

nanogpt_list_video_models

• detailed (optional): Include pricing information (default: true)

​

nanogpt_list_3d_models

• detailed (optional): Include pricing information (default: true)

​

Resources

• nanogpt://raw/{id}: Raw JSON response from a previous API call
• nanogpt://image/{id}: Generated images stored during the session
• nanogpt://media/{id}: Generated audio and other media stored during the session

​

Error Handling

​

Billing

• All paid tools deduct from your NanoGPT balance
• Use nanogpt_get_balance to check your balance before expensive operations
• Model listing tools are free to use
• Video and 3D jobs are charged when submitted; use poll to keep waiting instead of submitting again

​

Troubleshooting

​

”Missing required env var: NANOGPT_API_KEY”

claude mcp add nanogpt --scope user \
  --env NANOGPT_API_KEY=your_actual_key_here \
  -- npx -y @nanogpt/mcp

claude mcp add nanogpt --scope user --env NANOGPT_API_KEY=your_actual_key_here -- cmd /c "C:\Program Files\nodejs\npx.cmd" -y @nanogpt/mcp

​

”Invalid API key” errors

1. Verify your API key at nano-gpt.com/api
2. Make sure you’re using the full API key value
3. Check for extra spaces or newlines in the key
4. Verify that your Claude Code MCP launch command is correct, especially on Windows where npx should be run via cmd /c "C:\Program Files\nodejs\npx.cmd".

​

Requests timing out

claude mcp add nanogpt --scope user \
  --env NANOGPT_API_KEY=your_key \
  --env NANOGPT_TIMEOUT_MS=900000 \
  -- npx -y @nanogpt/mcp

claude mcp add nanogpt --scope user --env NANOGPT_API_KEY=your_key --env NANOGPT_TIMEOUT_MS=900000 -- cmd /c "C:\Program Files\nodejs\npx.cmd" -y @nanogpt/mcp

​

Video or 3D tool calls time out

​

MCP server not connecting

1. Ensure Node.js 22+ is installed: node --version
2. Try removing and re-adding the MCP server
3. Check your MCP client’s logs for detailed error messages
4. If you already added NanoGPT using an older command, remove the existing nanogpt MCP entry and add it again with the updated command

​

Support

• Documentation: nano-gpt.com/docs
• Discord: Join our community for help and updates
• API Keys: nano-gpt.com/api

​

Privacy & Security

• Your API key is stored locally and only sent to NanoGPT servers
• The MCP server runs locally on your machine
• No data is logged or stored by the MCP server
• Chat messages and other content are processed according to NanoGPT’s privacy policy