# Photo AI Studio MCP Server

[![npm version](https://img.shields.io/npm/v/@photoaistudio/mcp-server.svg)](https://www.npmjs.com/package/@photoaistudio/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

AI photo generation, editing, and video creation MCP server for [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.com), [Windsurf](https://codeium.com/windsurf), and any MCP-compatible client.

Generate professional AI headshots, edit photos with 19 AI operations, and create AI videos, all from your AI assistant.

Powered by [Photo AI Studio](https://photoaistudio.com).

<p align="center">
  <a href="https://photoaistudio.com">
    <strong>Website</strong>
  </a> &bull;
  <a href="https://photoaistudio.com/api-keys">
    <strong>Get API Key</strong>
  </a> &bull;
  <a href="https://photoaistudio.com/pricing">
    <strong>Pricing</strong>
  </a> &bull;
  <a href="https://www.npmjs.com/package/@photoaistudio/mcp-server">
    <strong>npm</strong>
  </a>
</p>

---

## What Can You Do?

Ask your AI assistant things like:

- "Upload my photo and generate a professional headshot"
- "Remove the background from this image"
- "Make me look 10 years younger in this photo"
- "Change my hairstyle to curly blonde"
- "Swap my face onto this photo"
- "Upscale this image to higher resolution"
- "Create a video from this image with cinematic motion"
- "Show me available photo themes for women"

## Two ways to connect

**Remote, nothing to install.** Clients that support remote MCP servers — Claude and
ChatGPT among them — connect straight to the hosted server:

```
https://www.photoaistudio.com/api/mcp
```

Paste that into your client's custom connector or remote MCP server field and sign in
when prompted. Browsing themes and pricing works with no account; generating photos,
editing images, and creating videos ask you to authorize access first, and you can
revoke it at any time from your [API keys page](https://photoaistudio.com/api-keys).
Setup notes are at [photoaistudio.com/mcp](https://photoaistudio.com/mcp).

**Local, with this package.** Use the steps below when your client runs MCP servers as
local processes, or when you would rather authenticate with an API key than a browser
sign-in.

## Quick Start

### 1. Create a Free Account

Sign up at [photoaistudio.com](https://photoaistudio.com) — new accounts get **100 free credits**.

### 2. Get an API Key

Go to [photoaistudio.com/api-keys](https://photoaistudio.com/api-keys) to create your API key.

### 3. Configure Your AI Assistant

**Claude Desktop** (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "photoaistudio": {
      "command": "npx",
      "args": ["-y", "@photoaistudio/mcp-server"],
      "env": {
        "PHOTOAI_API_KEY": "pa_sk_your-key-here"
      }
    }
  }
}
```

**Cursor**: Add the same config in Cursor Settings > MCP Servers.

**Windsurf / VS Code Copilot**: Add to your MCP configuration file.

## Available Tools

### Photo Generation

| Tool | Description | Credits |
|------|-------------|---------|
| `generate_photo` | Generate AI photos from face images using 150+ themed styles or custom prompts | 100/photo |
| `browse_themes` | Browse all available photo themes, filter by gender or search by keyword | Free |

### Photo Editing

| Tool | Description | Credits |
|------|-------------|---------|
| `edit_image` | 19 AI-powered edit operations (see list below) | 3-100 |

**Edit operations**: `remove_background` (10 cr), `replace_background` (3 cr), `retouch`, `skin`, `hair`, `makeup`, `age`, `expression`, `body_type`, `eye_color`, `color_correction`, `custom`, `clothes`, `try_on`, `product`, `upscale`, `restore`, `face_swap`, `extend` (100 cr each)

### Video Creation

| Tool | Description | Credits |
|------|-------------|---------|
| `create_video` | Create AI videos from images | 100-500 |

**Video types**: `image_to_video` (500 cr) — animate any photo, `ugc` (500 cr) — AI-generated spokesperson videos, `product_holder` (500 cr video / 100 cr image) — product showcase

### Utilities

| Tool | Description | Credits |
|------|-------------|---------|
| `upload_image` | Upload an image (URL or base64) to the CDN for use in other tools | Free |
| `get_account` | Check your credit balance and account info | Free |
| `get_prediction` | Check the status of an async operation | Free |
| `list_predictions` | List your past generations, edits, and videos | Free |

## How It Works

```
1. Upload your photo          →  upload_image (returns CDN URL)
2. Browse available styles     →  browse_themes (150+ options)
3. Generate AI photos          →  generate_photo (auto-waits for result)
4. Or edit your photo          →  edit_image (19 operations available)
5. Results returned directly   →  Auto-polls until complete
```

All operations are async but **auto-poll by default** — the tool waits and returns the final result URL. Set `wait_for_result: false` to get the prediction ID immediately for manual polling.

## Credits and Pricing

New accounts start with **100 free credits**.

| Package | Price | |
|---------|-------|-|
| 500 credits | $9 | [Buy](https://photoaistudio.com/pricing) |
| 1,000 credits | $15 | [Buy](https://photoaistudio.com/pricing) |
| 2,000 credits | $25 | [Buy](https://photoaistudio.com/pricing) |
| 4,000 credits | $35 | [Buy](https://photoaistudio.com/pricing) |
| 8,000 credits | $80 | [Buy](https://photoaistudio.com/pricing) |
| 20,000 credits | $190 | [Buy](https://photoaistudio.com/pricing) |

Monthly subscriptions also available at [photoaistudio.com/pricing](https://photoaistudio.com/pricing).

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PHOTOAI_API_KEY` | Yes | Your API key from [photoaistudio.com/api-keys](https://photoaistudio.com/api-keys) |
| `PHOTOAI_BASE_URL` | No | API base URL (default: `https://photoaistudio.com`) |

## Examples

### Generate a Professional Headshot

```
User: "Upload this photo and generate a professional headshot"

1. upload_image → CDN URL
2. browse_themes (gender: "female", tag: "professional") → theme slug
3. generate_photo (images: [CDN URL], gender: "female", category: "professional") → result URL
```

### Remove Background

```
User: "Remove the background from this image"

1. upload_image → CDN URL
2. edit_image (operation: "remove_background", image_url: CDN URL) → result URL
```

### Face Swap

```
User: "Swap my face onto this celebrity photo"

1. upload_image (source face) → source CDN URL
2. upload_image (target photo) → target CDN URL
3. edit_image (operation: "face_swap", source_image_url, target_image_url) → result URL
```

## Tech Stack

- TypeScript
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- stdio transport (runs locally, calls Photo AI Studio API over HTTPS)

## Links

- [Photo AI Studio](https://photoaistudio.com) — Main website
- [API Keys](https://photoaistudio.com/api-keys) — Create and manage API keys
- [Pricing](https://photoaistudio.com/pricing) — Credit packages and subscriptions
- [Photo Themes](https://photoaistudio.com/s/all) — Browse 150+ AI photo styles
- [npm Package](https://www.npmjs.com/package/@photoaistudio/mcp-server)

## License

[MIT](LICENSE)