# 🤖 PhotoForge MCP Server — AI Fashion Studio, 4K Mocap Video & Creative Tools

[![MCP](https://img.shields.io/badge/MCP-Protocol_2024--11--05-blue?style=for-the-badge&logo=anthropic)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Tools](https://img.shields.io/badge/Tools-28_Built--In-green?style=for-the-badge)](https://photoforge.ai/mcp)
[![Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Compatible-purple?style=for-the-badge)](https://claude.ai)
[![Cursor](https://img.shields.io/badge/Cursor-Compatible-black?style=for-the-badge)](https://cursor.com)

Official **Model Context Protocol (MCP)** server for **PhotoForge AI** (https://photoforge.ai).

Enables AI agents (Claude Desktop, Cursor, Antigravity, Windsurf, Poe, etc.) to direct studio-grade fashion photoshoots, execute on-model garment try-ons, animate 4K kinematic video motion capture, perform background swaps, and publish directly to Shopify, Notion, and social channels.

---

## ⚡ Quick Start

### 1. Claude Desktop Configuration
Add the server definition to your `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "photoforge": {
      "command": "npx",
      "args": ["-y", "photoforge-mcp"],
      "env": {
        "PHOTOFORGE_MCP_API_KEY": "YOUR_PHOTOFORGE_API_KEY",
        "PHOTOFORGE_SERVER_URL": "https://photoforge.ai"
      }
    }
  }
}
```

Or connect directly via local clone:
```json
{
  "mcpServers": {
    "photoforge": {
      "command": "node",
      "args": ["/path/to/photoforge-mcp/index.js"],
      "env": {
        "PHOTOFORGE_MCP_API_KEY": "YOUR_PHOTOFORGE_API_KEY"
      }
    }
  }
}
```

### 2. Cursor Configuration (`~/.cursor/mcp.json` or Project Settings)
```json
{
  "mcpServers": {
    "photoforge": {
      "command": "node",
      "args": ["/path/to/photoforge-mcp/index.js"],
      "env": {
        "PHOTOFORGE_MCP_API_KEY": "YOUR_PHOTOFORGE_API_KEY"
      }
    }
  }
}
```

### 3. Remote SSE Transport (No Local Install Required)
Connect your MCP client directly to the hosted Server-Sent Events endpoint:
- **Server URL**: `https://photoforge.ai/api/mcp`
- **Authentication**: `Bearer YOUR_API_KEY` (or `?apiKey=user_...`)

Get your API key at [photoforge.ai/mcp](https://photoforge.ai/mcp) (or use your Clerk User ID).

---

## 🛠️ Complete MCP Tools Catalog (28 Tools)

| Tool | Category | Description | Key Parameters |
| :--- | :--- | :--- | :--- |
| `generate_photo` | Generation | Generates ultra-photorealistic studio fashion photography and portraits. | `prompt`, `userImage`, `style`, `lighting`, `pose`, `background`, `quality` |
| `change_background` | Editing | Replaces or synthesizes a new studio environment or scene backdrop. | `imageUrl`, `backgroundPrompt`, `lightingMatch` |
| `remove_background` | Editing | Extracts subjects cleanly with transparent alpha masking. | `imageUrl` |
| `upscale_photo` | Editing | Restores micro-textures and enhances resolution to 4K studio quality. | `imageUrl`, `scaleFactor` |
| `generate_video` | Video | Generates motion-captured 4K vertical runway and dance videos. | `prompt`, `referenceVideoUrl`, `modelEngine`, `durationSeconds` |
| `combine_videos` | Video | Stitches multi-angle takes into commercial campaign sequences. | `videoUrls`, `transitionType` |
| `generate_production_script` | Video | Directs storyboard scenes, kinematic camera paths, and scripts. | `concept`, `targetAudience`, `durationSeconds` |
| `film_studio_skills` | Video | Introspects camera kinematics, sensor specs, and lens simulations. | *(none)* |
| `list_identities` | Identity | Lists registered AI model digital twins and facial profiles. | *(none)* |
| `create_identity` | Identity | Enrolls a new facial likeness profile for consistent model generation. | `name`, `faceImageUrl` |
| `delete_identity` | Identity | Removes an AI identity profile. | `identityId` |
| `list_photo_packs` | Packs | Catalogs 160+ curated photoshoot style packs. | `category` |
| `search_photo_packs` | Packs | Searches style recipes by aesthetic keywords or themes. | `query` |
| `recommend_photo_pack` | Packs | Matches optimal photography packs to target industry or niche. | `goal`, `industry` |
| `improve_prompt` | Prompts | Converts rough concepts into studio-calibrated prompt directives. | `userPrompt`, `style` |
| `suggest_styles` | Prompts | Recommends high-converting visual styles for target platforms. | `category` |
| `generate_content_calendar` | Planning | Formulates editorial publishing calendars with photo/video briefs. | `niche`, `frequency`, `month` |
| `generate_caption` | Assets | Synthesizes viral captions and hashtag strategies for TikTok, IG, LinkedIn. | `imageDescription`, `platform` |
| `resize_image_for_platform` | Assets | Re-crops and frames assets for 9:16 vertical, 1:1 square, or 16:9 banner. | `imageUrl`, `platform` |
| `export_to_shopify` | Connectors | Syncs editorial product imagery directly into Shopify product listings. | `imageUrl`, `productTitle`, `description` |
| `export_to_social` | Connectors | Schedules or pushes creative assets to social platforms. | `assetUrl`, `caption`, `channels` |
| `export_to_notion` | Connectors | Creates brand shoot entries and production briefs in Notion workspaces. | `assetUrl`, `pageTitle`, `notes` |
| `export_to_fanvue` | Connectors | Uploads and manages creator gallery drops on Fanvue. | `imageUrl`, `caption`, `isPaywalled` |
| `remaining_credits` | Account | Checks remaining generation credits and quota. | *(none)* |
| `subscription_status` | Account | Returns active plan tier, licensing permissions, and renewal dates. | *(none)* |
| `list_generations` | Workspace | Fetches historical generated assets and studio shoot metadata. | `limit`, `offset` |
| `delete_generation` | Workspace | Deletes an asset from the studio gallery. | `generationId` |
| `favorite_generation` | Workspace | Favorites, stars, or renames gallery assets. | `generationId`, `name`, `isFavorite` |

---

## 📦 MCP Resources & Prompts

### Resources
- `photoforge://packs` — Complete catalog of 160+ photoshoot packs with prompts and categories.
- `photoforge://styles` — Studio lighting presets (Softbox, Golden Hour, Moody, Flash).
- `photoforge://user/history` — Authenticated user's recent studio generations and metadata.
- `photoforge://user/identities` — Registered facial likeness models and digital twins.

### Prompts
- `linkedin_executive_headshot` — 85mm f/1.4 studio portrait for executive profiles.
- `luxury_travel_editorial` — High-fashion travel and destination photography.
- `swaptok_video_clone` — Dynamic 9:16 vertical video motion clone.
- `ecommerce_product_shoot` — Commercial product advertising photography.

---

## 🧪 Testing with MCP Inspector

Test the server locally in seconds:

```bash
npx @modelcontextprotocol/inspector node ./index.js
```

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.