> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nano-gpt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Use NanoGPT via MCP-compatible clients

# NanoGPT MCP Integration

The NanoGPT MCP (Model Context Protocol) server allows you to use NanoGPT's AI capabilities directly from MCP-compatible clients like Claude Code, Cursor, and other AI coding assistants.

## Features

The NanoGPT MCP server provides the following tools:

| Tool                         | Description                                              |
| ---------------------------- | -------------------------------------------------------- |
| `nanogpt_chat`               | Send chat messages to any AI model available on NanoGPT  |
| `nanogpt_get_balance`        | Check your account balance (USD and Nano)                |
| `nanogpt_image_generate`     | Generate images using DALL-E, Flux, Midjourney, and more |
| `nanogpt_web_search`         | Search the web for current information                   |
| `nanogpt_scrape_urls`        | Extract content from web pages                           |
| `nanogpt_youtube_transcribe` | Get transcripts from YouTube videos                      |
| `nanogpt_list_text_models`   | List available text/chat models                          |
| `nanogpt_list_image_models`  | List available image generation models                   |
| `nanogpt_list_audio_models`  | List available audio models (TTS/STT)                    |
| `nanogpt_list_video_models`  | List available video generation models                   |
| `nanogpt_vision`             | Analyze images with vision-capable models                |

## Prerequisites

* A NanoGPT account with an API key ([get one here](https://nano-gpt.com/api))
* Node.js 22.x or later
* An MCP-compatible client (Claude Code, Cursor, etc.)

## Installation

### Option 1: Using npx (Recommended)

The easiest way to use the NanoGPT MCP server is via `npx`.

#### Claude Code

**macOS / Linux**

```bash theme={null}
claude mcp add nanogpt --scope user \
  --env NANOGPT_API_KEY=YOUR_API_KEY \
  -- npx -y @nanogpt/mcp
```

**Windows**

```powershell theme={null}
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.

Replace `YOUR_API_KEY` with your actual NanoGPT API key.

### Option 2: Global Installation

```bash theme={null}
npm install -g @nanogpt/mcp
```

Then add to your MCP client:

```bash theme={null}
claude mcp add nanogpt --scope user \
  --env NANOGPT_API_KEY=YOUR_API_KEY \
  -- nanogpt-mcp
```

## Configuration

### Required Environment Variables

| Variable          | Description                     |
| ----------------- | ------------------------------- |
| `NANOGPT_API_KEY` | Your NanoGPT API key (required) |

### Optional Environment Variables

| Variable                | Default                      | Description                                 |
| ----------------------- | ---------------------------- | ------------------------------------------- |
| `NANOGPT_TIMEOUT_MS`    | `600000` (10 min)            | Request timeout in milliseconds             |
| `NANOGPT_DEFAULT_MODEL` | `claude-sonnet-4-5-20250929` | Default model for chat requests             |
| `NANOGPT_LOG_LEVEL`     | `info`                       | Log level: `debug`, `info`, `warn`, `error` |
| `NANOGPT_BASE_URL`      | `https://nano-gpt.com`       | Base URL for the NanoGPT API                |
| `NANOGPT_AUTH_MODE`     | `bearer`                     | Auth mode: `bearer`, `x-api-key`, or `both` |
| `NANOGPT_MAX_RETRIES`   | `0`                          | Number of retry attempts                    |

## Usage Examples

Once configured, you can use NanoGPT tools directly from your MCP client. Here are some examples:

### Check Your Balance

Ask your AI assistant:

> "Check my NanoGPT balance"

The assistant will call `nanogpt_get_balance` and show your USD and Nano balances.

### 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"

### Get YouTube Transcripts

> "Use NanoGPT to get the transcript of this YouTube video: [https://www.youtube.com/watch?v=](https://www.youtube.com/watch?v=)..."

### Scrape Web Pages

> "Use NanoGPT to scrape the content from [https://example.com](https://example.com)"

## Tool Reference

### nanogpt\_chat

Send a chat completion request to an AI model.

**Parameters:**

* `messages` (required): Array of message objects with `role` ("system", "user", "assistant") and `content`
* `model` (optional): Model ID (defaults to Claude Sonnet 4.5)
* `temperature` (optional): Sampling temperature (0-2)
* `max_tokens` (optional): Maximum tokens in response

**Example:**

```json theme={null}
{
  "messages": [
    {"role": "user", "content": "Explain quantum computing in simple terms"}
  ],
  "model": "openai/gpt-5.2"
}
```

### nanogpt\_get\_balance

Check your current account balance.

**Parameters:** None

**Returns:**

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

### nanogpt\_image\_generate

Generate images from text prompts.

**Parameters:**

* `prompt` (required): Text description of the image to generate
* `model` (optional): Image model to use (e.g., "dall-e-3", "flux-pro")
* `n` (optional): Number of images to generate (1-10)
* `size` (optional): Image size (e.g., "1024x1024")
* `quality` (optional): Image quality setting

**Example:**

```json theme={null}
{
  "prompt": "A serene mountain landscape at dawn",
  "model": "flux-pro",
  "size": "1024x1024"
}
```

### nanogpt\_web\_search

Search the web for current information.

**Parameters:**

* `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)

**Example:**

```json theme={null}
{
  "query": "latest developments in fusion energy",
  "depth": "deep",
  "outputType": "sourcedAnswer"
}
```

### nanogpt\_vision

Analyze images using vision-capable models.

**Parameters:**

* `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

**Example:**

```json theme={null}
{
  "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-5.2"
}
```

### nanogpt\_scrape\_urls

Scrape content from web pages.

**Parameters:**

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

**Example:**

```json theme={null}
{
  "urls": ["https://example.com/article1", "https://example.com/article2"]
}
```

### nanogpt\_youtube\_transcribe

Get transcripts from YouTube videos.

**Parameters:**

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

**Example:**

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

### nanogpt\_list\_text\_models

List available text/chat models.

**Parameters:**

* `detailed` (optional): Include pricing information (default: false)

### nanogpt\_list\_image\_models

List available image generation models.

**Parameters:**

* `detailed` (optional): Include pricing information (default: true)

### nanogpt\_list\_audio\_models

List available audio models.

**Parameters:**

* `detailed` (optional): Include pricing information (default: true)
* `type` (optional): Filter by type: "tts", "stt", or "all"

### nanogpt\_list\_video\_models

List available video generation models.

**Parameters:**

* `detailed` (optional): Include pricing information (default: true)

## Resources

Resources allow agents to access data saved during a session:

* **`nanogpt://raw/{id}`**: Raw JSON response from a previous API call
* **`nanogpt://image/{id}`**: Generated images stored during the session

## Error Handling

The MCP server provides clear error messages for common issues:

| Error                | Meaning                 | Solution                                                    |
| -------------------- | ----------------------- | ----------------------------------------------------------- |
| Invalid API key      | Authentication failed   | Check your `NANOGPT_API_KEY` and MCP launch command         |
| Insufficient balance | Account balance too low | Top up your account at [nano-gpt.com](https://nano-gpt.com) |
| Rate limited         | Too many requests       | Wait and try again                                          |
| Timeout              | Request took too long   | Try a simpler request or increase `NANOGPT_TIMEOUT_MS`      |

## 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
* Failed requests (timeouts, errors) are not charged

## Troubleshooting

### "Missing required env var: NANOGPT\_API\_KEY"

**macOS / Linux**

```bash theme={null}
claude mcp add nanogpt --scope user \
  --env NANOGPT_API_KEY=your_actual_key_here \
  -- npx -y @nanogpt/mcp
```

**Windows**

```powershell theme={null}
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
```

Make sure you set your API key when adding the MCP server. If you re-add the server later, include `--env NANOGPT_API_KEY=...` again.

### "Invalid API key" errors

An immediate `Invalid API key` error can be caused by a broken MCP launcher command, not just a bad key value.

1. Verify your API key at [nano-gpt.com/api](https://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

For long-running operations like web search, you can increase the timeout:

**macOS / Linux**

```bash theme={null}
claude mcp add nanogpt --scope user \
  --env NANOGPT_API_KEY=your_key \
  --env NANOGPT_TIMEOUT_MS=900000 \
  -- npx -y @nanogpt/mcp
```

**Windows**

```powershell theme={null}
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
```

### 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](https://nano-gpt.com/docs)
* **Discord:** Join our community for help and updates
* **API Keys:** [nano-gpt.com/api](https://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](https://nano-gpt.com/privacy)