<p align="center">
  <img src="https://www.atlascloud.ai/logo.svg" alt="Atlas Cloud" width="80" />
</p>

<h1 align="center">Atlas Cloud MCP Server</h1>

<p align="center">
  <a href="https://www.npmjs.com/package/atlascloud-mcp"><img src="https://img.shields.io/npm/v/atlascloud-mcp.svg?style=flat&colorA=18181B&colorB=28CF8D" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/atlascloud-mcp"><img src="https://img.shields.io/npm/dm/atlascloud-mcp.svg?style=flat&colorA=18181B&colorB=28CF8D" alt="npm downloads" /></a>
  <a href="https://github.com/AtlasCloudAI/mcp-server"><img src="https://img.shields.io/github/license/AtlasCloudAI/mcp-server?style=flat&colorA=18181B&colorB=28CF8D" alt="license" /></a>
  <a href="https://github.com/AtlasCloudAI/mcp-server"><img src="https://img.shields.io/github/stars/AtlasCloudAI/mcp-server?style=flat&colorA=18181B&colorB=28CF8D" alt="github stars" /></a>
  <a href="https://github.com/AtlasCloudAI/mcp-server/pulls"><img src="https://img.shields.io/badge/PRs-welcome-28CF8D.svg?style=flat&colorA=18181B&colorB=28CF8D" alt="PRs Welcome" /></a>
</p>

<p align="center">
  English | <a href="./docs/README.zh-CN.md">中文</a> | <a href="./docs/README.ja.md">日本語</a> | <a href="./docs/README.ko.md">한국어</a> | <a href="./docs/README.es.md">Español</a> | <a href="./docs/README.fr.md">Français</a>
</p>

<p align="center">
  Use <a href="https://www.atlascloud.ai?utm_source=github&utm_campaign=mcp-server">Atlas Cloud</a>'s 300+ image / video / LLM models in Claude Code, Codex, Gemini CLI, Cursor, Cline and more. Generate images, videos & chat via standard MCP tools.
</p>

<p align="center">
  <a href="https://www.atlascloud.ai/console/api-keys?utm_source=github&utm_campaign=mcp-server"><b>→ Get your free Atlas Cloud API key</b></a> · 300+ models · OpenAI-compatible
</p>

---

## Supported Models

<!-- ATLAS-MODELS:START lang=en campaign=mcp-server -->
<!-- ⚠️ Auto-generated from the live model catalog by AtlasCloudAI/.github/scripts/update-models-readme.mjs — do not edit by hand. -->
- 🎬 **Video** (200) — MiniMax H3 Max · MiniMax H3 Fast · Gemini Omni 1.1 Flash · MiniMax H3 · Wan-3.0-Prime · Wan-3.0
- 🎨 **Image** (126) — GPT Image 2.5 Sunburst · GPT Image 2.5 Flare · Seedream v4.7 · MAI-Image-2.5-Pro
- 🧊 **3D** (7) — Seed3D 2.0 · Tripo H3.1 · Hunyuan 3D Rapid · Hunyuan 3D Pro
- 💬 **LLM** (70) — DeepSeek V4 Pro 0813 · Grok 4.6 · DeepSeek V4 Flash Vision Exp · DeepSeek V4 Flash 0731
- 🔊 **Audio (TTS · Music · ASR)** (17) — Suno chirp-v4-5-all · Suno chirp-v4-5-plus · Suno chirp-auk · Suno chirp-fenix

- 📚 **Explore more** — [all 443 live models »](https://www.atlascloud.ai/models?utm_source=github&utm_campaign=mcp-server)
<!-- ATLAS-MODELS:END -->

> 🎬 **Newest video models** — Seedance 2.5 · Kling 4.0 · Wan 3.0 · Kling Video O3.


## Contents

- [What You Can Do](#what-you-can-do)
- [Quick Start](#quick-start)
- [Available Tools](#available-tools)
- [Usage Examples](#usage-examples)
- [Development](#development)
- [More Atlas Cloud Tools](#more-atlas-cloud-tools)
- [License](#license)

## What You Can Do

Ask your AI assistant in plain language — it discovers the right model, builds the parameters, and submits the job:

- 🎨 **"Make a hero image for this blog post"** — text-to-image across Nano Banana Pro, GPT Image 2, Flux 2, Seedream, Imagen…
- 🎬 **"Turn this product photo into a 5-second ad"** — image-to-video with Seedance 2.5, Kling 3, Kling Video O3, Veo 3.1…
- 🧊 **"Make a 3D model from this photo"** — image-to-3D / text-to-3D with Hunyuan 3D (GLB/OBJ/USDZ output)
- 🔊 **"Read this script aloud"** — text-to-speech with Seed Audio, ElevenLabs, xAI TTS
- 🎵 **"Write a theme song for my app"** — music generation with Suno, MiniMax Music
- 📝 **"Transcribe this meeting recording"** — speech-to-text with Seed ASR, xAI STT
- 🎞️ **"Storyboard this script into 6 shots"** — chain LLM → image → video inside one conversation
- ✏️ **"Edit this image — add a hat"** — upload a local file, then run an image-editing model
- 💸 **"How much credit is left, and what did I spend this month?"** — check balance, usage, and cost breakdowns
- 💬 **"What is in this screenshot?"** — LLM chat with Claude, GPT, DeepSeek, Qwen, Gemini, GLM…, including image/video input on models that accept it
- 🕓 **"What did I generate yesterday?"** — browse generation history and pull back the output URLs

Under the hood: model discovery, dynamic per-model parameter schemas (validated before every request so invalid params fail fast without spending credits, plus a `dry_run` flag on every generation tool that shows the exact request body without submitting it), media upload, one-step quick-generate, generation history, account balance & usage, and documentation search — all exposed as standard MCP tools (see [Available Tools](#available-tools)).

LLM calls are protocol-aware: each model is called through the contract it actually declares — OpenAI chat completions, OpenAI Responses, Anthropic Messages, or native Gemini `generateContent` — so Gemini-native models work without any special handling on your side.

## Quick Start

### Prerequisites

- Node.js >= 18
- Atlas Cloud API Key — [Get one free at atlascloud.ai](https://www.atlascloud.ai/console/api-keys?utm_source=github&utm_campaign=mcp-server)

See [`.env.example`](./.env.example) for the environment variable to set.

### CLI agents (one-line install)

The fastest path — these AI coding agents add the server with a single command:

```bash
# Claude Code
claude mcp add atlascloud -- npx -y atlascloud-mcp

# OpenAI Codex CLI
codex mcp add atlascloud -- npx -y atlascloud-mcp

# Gemini CLI
gemini mcp add atlascloud -- npx -y atlascloud-mcp

# Goose CLI
goose mcp add atlascloud -- npx -y atlascloud-mcp
```

> Set the `ATLASCLOUD_API_KEY` environment variable in your shell first.

### IDEs, editors & extensions (JSON config)

Add this to your client's MCP configuration — works with every MCP-compatible client:

```json
{
  "mcpServers": {
    "atlascloud": {
      "command": "npx",
      "args": ["-y", "atlascloud-mcp"],
      "env": {
        "ATLASCLOUD_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

| Client | Where to add it |
|--------|-----------------|
| [Cursor](https://cursor.com) | Settings → MCP → Add Server |
| [Cline](https://github.com/cline/cline) | MCP Marketplace → Add Server |
| [Continue](https://continue.dev) | `config.yaml` → MCP |
| [Windsurf](https://codeium.com/windsurf) | Settings → MCP → Add Server |
| [VS Code (Copilot)](https://code.visualstudio.com) | `.vscode/mcp.json` or Settings → MCP |
| [Trae](https://trae.ai) | Settings → MCP → Add Server |
| [JetBrains IDEs](https://www.jetbrains.com) | Settings → Tools → AI Assistant → MCP |
| [ChatGPT Desktop](https://openai.com/chatgpt/desktop) | Settings → MCP |
| [Amazon Q Developer](https://aws.amazon.com/q/developer/) | MCP Configuration |
| [Roo Code](https://github.com/RooCodeInc/Roo-Code) | Settings → MCP → Add Server |

### Prefer Skills?

If you'd rather use Skills than MCP, we also ship an [Atlas Cloud Skills](https://github.com/AtlasCloudAI/atlas-cloud-skills) package for Claude Code and other skill-compatible agents.

## Available Tools

| Tool | Description |
|------|-------------|
| `atlas_search_docs` | Search Atlas Cloud documentation and models by keyword |
| `atlas_list_models` | List available models, filtered by type (Text/Image/Video/Audio), sub-kind (3d/tts/stt/music/lyrics) or keyword |
| `atlas_get_model_info` | Get detailed model info including API schema, parameters, and usage examples |
| `atlas_generate_image` | Generate images and 3D models (image-to-3D / text-to-3D) with any supported Image model |
| `atlas_generate_video` | Generate videos with any supported video model |
| `atlas_generate_audio` | Generate audio — speech (TTS) and music/songs (Suno, MiniMax Music) — with any supported audio model |
| `atlas_transcribe_audio` | Transcribe speech to text (ASR) — meetings, interviews, voice notes |
| `atlas_quick_generate` | One-step image/video/audio generation — auto-finds model by keyword, builds params, and submits |
| `atlas_upload_media` | Upload a local image, audio, video or document and get a URL to pass to any model |
| `atlas_chat` | Chat with LLM models — endpoint and request format are picked automatically per model (OpenAI chat/responses, Anthropic messages, native Gemini); supports image/video/audio input |
| `atlas_get_prediction` | Check status and result of a generation task — media URLs, transcripts, lyrics, cover art and cost |
| `atlas_list_predictions` | Browse past generation tasks — recover a lost prediction ID or review earlier results |
| `atlas_get_balance` | Get the account balance and credit summary for your API key |
| `atlas_get_model_usage` | Get daily model usage (requests, tokens, image/video counts) over a date range |
| `atlas_get_model_costs` | Get daily model cost (spend) buckets over a date range |

## Usage Examples

### Search for models

> "Search Atlas Cloud for video generation models"

Your AI assistant will use `atlas_search_docs` or `atlas_list_models` to find relevant models.

### Generate an image

> "Generate an image of a cat in space using Seedream"

The assistant will:
1. Use `atlas_list_models` to find Seedream image models
2. Use `atlas_get_model_info` to get the model's parameters
3. Use `atlas_generate_image` with the correct parameters

### Generate a video

> "Create a video of a rocket launch using Kling v3"

The assistant will:
1. Find the Kling video model
2. Get its schema to understand required parameters
3. Use `atlas_generate_video` with appropriate parameters

### Upload a local image for editing or video generation

> "Edit this image /Users/me/photos/cat.jpg to add a hat"

The assistant will:
1. Use `atlas_upload_media` to upload the local file and get a URL
2. Find an image-editing model
3. Use `atlas_generate_image` with the uploaded URL

> **Note**: Uploaded files are for temporary use with Atlas Cloud generation tasks only. Files may be cleaned up periodically. Do not use this as permanent file hosting — abuse may result in API key suspension.

### Generate speech (TTS)

> "Read this sentence aloud with Seed Audio: Welcome to Atlas Cloud"

The assistant will:
1. Use `atlas_list_models` with `type="Audio"` to find the TTS model
2. Use `atlas_generate_audio` with the text to synthesize
3. Use `atlas_get_prediction` to retrieve the generated audio URL

### Generate music

> "Make a 30-second upbeat synthwave track for my product demo with Suno"

Music models (Suno Chirp, MiniMax Music) are Audio-type models, so the assistant uses `atlas_generate_audio` with a song description (and optionally lyrics), then retrieves the audio URL via `atlas_get_prediction`.

### Transcribe audio (speech-to-text)

> "Transcribe this interview recording: https://example.com/interview.mp3"

The assistant uses `atlas_transcribe_audio` with a speech-to-text model (e.g., `bytedance/seed-asr-2.0`) and the `audio_url`, then retrieves the transcript via `atlas_get_prediction`. For local files, it first calls `atlas_upload_media` to get a URL.

### Generate a 3D model

> "Turn this product photo into a 3D model with Hunyuan 3D"

3D models are Image-type models, so the assistant uses `atlas_generate_image` with the `image` parameter and retrieves a GLB/OBJ/USDZ file via `atlas_get_prediction`.

### Chat with an LLM

> "Ask Qwen to explain quantum computing"

The assistant will use `atlas_chat` with the Qwen model. For a model that accepts images or video, attach them to the message and they are converted to that model's protocol automatically.

### Check a call before paying for it

> "Show me exactly what you'd send to Kling for this, don't run it yet"

Every generation tool takes `dry_run: true` — it resolves the model, builds the request, validates it against the model's schema, prints the exact JSON body, and stops. Nothing is submitted and nothing is billed. Useful when a media URL could land on more than one input field, or when a keyword could match several models.

### Find an earlier generation

> "What did I generate yesterday? Give me the video link again"

The assistant uses `atlas_list_predictions` to list recent tasks and `atlas_get_prediction` for the full result. This is also how to recover a task whose prediction ID was lost — the job keeps running (and is billed) even if the submitting call timed out.

### Check balance and usage

> "How much Atlas Cloud credit do I have left, and what did I spend this month?"

The assistant will use `atlas_get_balance` for the current balance and `atlas_get_model_costs` for the spend breakdown.

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev
```

## More Atlas Cloud Tools

- 🧰 **Want to use it from the terminal?** → [atlascloud-cli](https://github.com/AtlasCloudAI/cli)
- 🤖 **Want to use it in Claude Code / Cursor?** → [Atlas Cloud MCP Server](https://github.com/AtlasCloudAI/mcp-server)
- 🎬 **Want it as a Claude Code / Codex / Gemini CLI Skill?** → [atlas-cloud-skills](https://github.com/AtlasCloudAI/atlas-cloud-skills)
- 🎨 **ComfyUI nodes** → [atlascloud_comfyui](https://github.com/AtlasCloudAI/atlascloud_comfyui)
- 🔁 **n8n nodes** → [n8n-nodes-atlascloud](https://github.com/AtlasCloudAI/n8n-nodes-atlascloud)
- 💬 **Join our Discord** → [discord.gg/MWmMr4q9es](https://discord.gg/MWmMr4q9es)
- 🌐 **Website** → [atlascloud.ai](https://www.atlascloud.ai?utm_source=github&utm_campaign=mcp-server)

## License

MIT