<p align="center">
  <img src="assets/icon.png" alt="Artifex MCP" width="128" height="128">
</p>

<h1 align="center">Artifex MCP</h1>

> **⚠️ UNOFFICIAL TOOL**: This is an independent, community-developed MCP server. It is not affiliated with, endorsed by, or supported by Google or OpenAI. Use at your own risk.

MCP (Model Context Protocol) server for AI image generation supporting multiple providers:

- **Antigravity** (default) - Google's Gemini 3 Pro Image model
- **OpenAI** - DALL-E 3

## Features

- **Multi-Provider Support**: Switch between Antigravity and OpenAI with a simple parameter
- **Text-to-Image**: Generate images from text descriptions
- **Image Editing**: Modify existing images with text instructions (Antigravity only)
- **Multiple Outputs**: Generate up to 4 image variations per request (Antigravity only)
- **Character Consistency**: Session-based generation for consistent characters (Antigravity only)
- **Multiple Aspect Ratios**: 1:1, 16:9, 9:16, 3:4, 4:3, and more

## Installation

Run directly with npx (recommended):

```bash
npx artifex-mcp
```

Or install globally:

```bash
npm install -g artifex-mcp
```

## Authentication

### Antigravity (Default)

```bash
npx artifex-mcp --login
```

This will:
1. Open your browser for Google OAuth
2. Store credentials securely in `~/.config/artifex-mcp/auth.json`

### OpenAI

Set the `OPENAI_API_KEY` environment variable:

```bash
export OPENAI_API_KEY=sk-...
```

## Usage

### As an MCP Server

Add to your MCP client configuration:

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "artifex": {
      "command": "npx",
      "args": ["artifex-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

**OpenCode**:
```json
{
    "mcp": {
        "artifex": {
            "type": "local",
            "command": ["npx", "artifex-mcp"],
            "enabled": true,
            "env": {
                "OPENAI_API_KEY": "sk-..."
            }
        }
    }
}
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `DEFAULT_IMAGE_PROVIDER` | Default provider to use | `antigravity` |
| `DEFAULT_IMAGE_MODEL` | Default model for the provider | `gemini-3-pro-image` |
| `OPENAI_API_KEY` | API key for OpenAI provider | - |

### Provider Selection

Use the `model` parameter with `provider:model` format:

```
# Use Antigravity (default)
generate_image({ prompt: "a cat" })

# Use OpenAI DALL-E 3
generate_image({ prompt: "a cat", model: "openai:dall-e-3" })

# Use a specific Antigravity model
generate_image({ prompt: "a cat", model: "antigravity:gemini-3-pro-image" })
```

### Available Tools

#### `generate_image`

Generate images from text prompts.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Image description or editing instruction |
| `model` | string | No | env default | Provider and model in `provider:model` format |
| `aspect_ratio` | enum | No | "1:1" | 1:1, 16:9, 9:16, 3:4, 4:3, 2:3, 3:2, 4:5, 5:4, 21:9 |
| `output_path` | string | No | cwd | Directory to save images |
| `file_name` | string | No | auto | Custom filename |
| `input_image` | string | No | - | Path to image for editing (Antigravity only) |
| `count` | number | No | 1 | Number of images 1-4 (Antigravity only) |
| `session_id` | string | No | - | For character consistency (Antigravity only) |

**Examples:**

```
# Default provider (Antigravity)
Generate a cyberpunk cityscape at night

# Using OpenAI
Generate a cyberpunk cityscape at night, model: openai:dall-e-3

# Multiple images (Antigravity only)
Generate 4 variations of a majestic dragon, aspect ratio 16:9

# Character consistency (Antigravity only)
Create a hero named Luna, session_id: luna
```

#### `auth_status`

Check authentication status for a provider.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `provider` | string | No | Provider to check (default: antigravity) |

#### `auth_login`

Get instructions for authenticating with a provider.

#### `auth_logout`

Delete stored credentials for a provider.

#### `quota_status`

Check rate limit and quota status for a provider.

## Provider Capabilities

| Feature | Antigravity | OpenAI |
|---------|-------------|--------|
| Text-to-Image | ✅ | ✅ |
| Image Editing | ✅ | ❌ |
| Multiple Images | ✅ (1-4) | ❌ (1 only) |
| Sessions | ✅ | ❌ |
| Aspect Ratios | ✅ | ✅ (limited) |
| Auth Type | Google OAuth | API Key |

## File Locations

| Purpose | Location |
|---------|----------|
| Credentials | `~/.config/artifex-mcp/auth.json` |
| Sessions | `~/.cache/artifex-mcp/sessions/` |
| Generated Images | Current working directory (or custom path) |

## Troubleshooting

### "Not authenticated" error (Antigravity)

```bash
npx artifex-mcp --login
```

### "OpenAI API key not found" error

Set the environment variable:
```bash
export OPENAI_API_KEY=sk-...
```

### Rate limit exceeded

Wait for the time indicated in the error message. Rate limits are enforced per-account.

### Unsupported feature error

Some features are only available on specific providers. For example:
- `session_id` only works with Antigravity
- `input_image` (editing) only works with Antigravity
- `count > 1` only works with Antigravity

## License

MIT

<details>
<summary><strong>Legal</strong></summary>

### Intended Use

- Personal / internal development only
- Respect quotas and data handling policies
- Not for production services or bypassing intended limits

### Warning

By using this plugin, you acknowledge:

- **Terms of Service risk** — This approach may violate ToS of AI model providers
- **Account risk** — Providers may suspend or ban accounts
- **No guarantees** — APIs may change without notice
- **Assumption of risk** — You assume all legal, financial, and technical risks

### Disclaimer

Not affiliated with Google or OpenAI. This is an independent open-source project.

"Antigravity", "Gemini", "Google Cloud", "Google", "OpenAI", and "DALL-E" are trademarks of their respective owners.

</details>