# midjourney-proxy-mcp

MCP server for [ImagineAPI](https://www.imagineapi.dev/) - generate Midjourney images from Claude, Cursor, and other AI tools.

## Features

- Generate Midjourney images via ImagineAPI
- Query image generation status and results
- List recent generations with filtering
- Access generation statistics via MCP resources

## Installation

```bash
# Using uvx (recommended)
uvx midjourney-proxy-mcp

# Using pip
pip install midjourney-proxy-mcp
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `IMAGINEAPI_URL` | ImagineAPI base URL | `https://cl.imagineapi.dev` |
| `IMAGINEAPI_TOKEN` | API authentication token | (required) |

Get your API token from [ImagineAPI](https://www.imagineapi.dev/).

### Claude Desktop

Add to your `claude_desktop_config.json`:

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

```json
{
  "mcpServers": {
    "midjourney": {
      "command": "uvx",
      "args": ["midjourney-proxy-mcp"],
      "env": {
        "IMAGINEAPI_URL": "https://your-imagineapi.com",
        "IMAGINEAPI_TOKEN": "your-api-token"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add midjourney --env IMAGINEAPI_TOKEN=your-api-token -- uvx midjourney-proxy-mcp
```

Or add manually to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "midjourney": {
      "command": "uvx",
      "args": ["midjourney-proxy-mcp"],
      "env": {
        "IMAGINEAPI_TOKEN": "your-api-token"
      }
    }
  }
}
```

Alternatively, create a `.env` file in your working directory:

```
IMAGINEAPI_TOKEN=your-api-token
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "midjourney": {
      "command": "uvx",
      "args": ["midjourney-proxy-mcp"],
      "env": {
        "IMAGINEAPI_URL": "https://your-imagineapi.com",
        "IMAGINEAPI_TOKEN": "your-api-token"
      }
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `midjourney_imagine` | Generate an image from a prompt (supports Midjourney syntax like `--ar 16:9`) |
| `midjourney_get_status` | Get generation status including progress, URLs, and upscaled images |
| `midjourney_list_images` | List recent generations with optional status filter |

### Tool Examples

**Generate an image:**
```
midjourney_imagine(prompt="A futuristic city at sunset --ar 16:9 --v 7")
```

**Check status:**
```
midjourney_get_status(image_id="abc123")
```

**List recent images:**
```
midjourney_list_images(limit=10, status="completed")
```

## Resources

| Resource URI | Description |
|--------------|-------------|
| `midjourney://generations` | List all recent generations |
| `midjourney://generations/{status}` | Filter generations by status (pending, in-progress, completed, failed) |
| `midjourney://generation/{id}` | Get details for a specific generation |
| `midjourney://stats` | Get generation statistics (total count, status breakdown, completion rate) |

## Image Status Flow

1. `pending` - Request received, queued for processing
2. `in-progress` - Midjourney is generating (progress percentage available)
3. `completed` - Done, `upscaled_urls` contains 4 upscaled images
4. `failed` - Error occurred, check `error` field

## Development

```bash
# Install dependencies
uv sync

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=midjourney_proxy_mcp

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/ tests/

# Format code
uv run ruff format src/ tests/

# Run server locally
uv run midjourney-proxy-mcp
```

## Related

- [ImagineAPI Documentation](https://docs.imagineapi.dev/)
- [MCP Protocol](https://modelcontextprotocol.io/)
- [FastMCP](https://github.com/jlowin/fastmcp)

## License

MIT
