# RunAPI MCP server

> Enables AI assistants to browse a catalog of 160+ generative models and execute tasks for image, video, music, and audio generation.

- Repository: https://github.com/runapi-ai/mcp
- Page: https://hostedmcp.org/servers/runapi-ai/mcp
- Transport: stdio, remote
- Stars: 56
- License: Apache-2.0
- Latest version: 0.17.0

## Install

### Claude Code

```sh
claude mcp add --env 'RUNAPI_API_KEY=<YOUR_RUNAPI_API_KEY>' mcp -- npx -y @runapi.ai/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@runapi.ai/mcp"
      ],
      "env": {
        "RUNAPI_API_KEY": "<YOUR_RUNAPI_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@runapi.ai/mcp"
      ],
      "env": {
        "RUNAPI_API_KEY": "<YOUR_RUNAPI_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@runapi.ai/mcp"],"env":{"RUNAPI_API_KEY":"<YOUR_RUNAPI_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@runapi.ai/mcp"
      ],
      "env": {
        "RUNAPI_API_KEY": "<YOUR_RUNAPI_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add mcp --env 'RUNAPI_API_KEY=<YOUR_RUNAPI_API_KEY>' -- npx -y @runapi.ai/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp]
command = "npx"
args = ["-y", "@runapi.ai/mcp"]

[mcp_servers.mcp.env]
RUNAPI_API_KEY = "<YOUR_RUNAPI_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'RUNAPI_API_KEY=<YOUR_RUNAPI_API_KEY>' mcp npx -- -y @runapi.ai/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@runapi.ai/mcp"
      ],
      "env": {
        "RUNAPI_API_KEY": "<YOUR_RUNAPI_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `RUNAPI_API_KEY` | no | yes | Optional RunAPI API key for headless hosts. Interactive MCP hosts can use the login tool, which writes shared RunAPI config. |

## Tools (9)

- `list_models`: List RunAPI models from the embedded catalog. Optional filters: modality, service, or action.
- `get_model_info`: Get supported endpoint, current runtime pricing, and input constraints for a RunAPI model slug. Add service and action when the model supports multiple endpoints.
- `list_actions`: List RunAPI endpoint names grouped by output modality.
- `check_pricing`: Return current runtime pricing for a RunAPI model/action pair.
- `search_prompts`: Search RunAPI prompt examples by modality, category, tags, text query, or model. Each prompt includes its approved example images in media; example videos and reference images are not returned. Free, no API key required.
- `check_balance`: Return the authenticated RunAPI account balance and spending metrics.
- `create_task`: Run a RunAPI operation with a caller-generated idempotency key. Asynchronous operations can optionally poll until completion.
- `get_task`: Fetch the current status and latest payload for an existing RunAPI task.
- `login`: Authenticate RunAPI by opening a browser PKCE login flow and saving the API key to ~/.config/runapi/config.json.

## FAQ

### Do I need an API key to browse models?

No, discovery tools like browsing the catalog and checking pricing work without an API key using an embedded build-time catalog.

### How can I use RunAPI in a headless or CI environment?

You can set the RUNAPI_API_KEY environment variable before starting the MCP host.

### Can I create tasks without waiting for them to finish?

Yes, you can call the create_task tool with the wait parameter set to false to receive a task ID immediately.

### Does this server run the AI models locally?

No, the package is a pure client and does not run a local generation backend.
