# midjourney-proxy-mcp

MCP (Model Context Protocol) server for ImagineAPI - a self-hosted Midjourney proxy service.

## Overview

This MCP server enables AI tools (Claude Desktop, Claude Code, Cursor, etc.) to generate images via Midjourney through the ImagineAPI REST API.

```
AI Tool (Claude/Cursor) --> MCP Server --> ImagineAPI REST API --> Midjourney
```

## Tech Stack

- **Language**: Python 3.11+
- **Framework**: FastMCP (MCP Python SDK)
- **Validation**: Pydantic v2
- **HTTP Client**: httpx (async)
- **Packaging**: uv / pip (pyproject.toml)
- **Documentation**: MkDocs Material
- **Testing**: pytest + pytest-asyncio

## Project Structure

```
midjourney-proxy-mcp/
├── src/
│   └── midjourney_proxy_mcp/
│       ├── __init__.py
│       ├── server.py              # FastMCP main server
│       ├── client.py              # ImagineAPI REST client
│       ├── config.py              # Environment config (Pydantic Settings)
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── imagine.py         # midjourney_imagine tool
│       │   ├── upscale.py         # midjourney_upscale tool
│       │   ├── variation.py       # midjourney_variation tool
│       │   └── query.py           # midjourney_get_status, midjourney_list_images
│       └── models.py              # Pydantic input/output models
├── tests/
│   ├── __init__.py
│   ├── conftest.py                # pytest fixtures
│   ├── test_server.py             # Server initialization tests
│   ├── test_client.py             # API client tests
│   └── test_tools/
│       ├── test_imagine.py
│       ├── test_upscale.py
│       ├── test_variation.py
│       └── test_query.py
├── docs/
│   ├── index.md                   # Home
│   ├── installation.md            # Installation guide
│   ├── configuration.md           # Config for each client
│   └── tools.md                   # Tool reference
├── mkdocs.yml
├── pyproject.toml
├── fastmcp.json                   # For fastmcp install command
├── LICENSE                        # MIT
├── README.md
└── PLAN.md                        # This file
```

## Tools Specification

### midjourney_imagine

Generate a new image from a text prompt.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string | Yes | Text prompt for Midjourney |
| ref_image_url | string | No | Reference image URL |
| wait_for_result | bool | No | Wait for completion (default: false) |
| timeout | int | No | Max wait time in seconds (default: 120) |

Returns: `{ image_id, status, url?, progress? }`

### midjourney_upscale

Upscale one of the 4 generated images.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| image_id | string | Yes | Original image ID |
| button | string | Yes | U1, U2, U3, or U4 |
| wait_for_result | bool | No | Wait for completion |

Returns: `{ new_image_id, status, url? }`

### midjourney_variation

Create a variation of one of the 4 generated images.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| image_id | string | Yes | Original image ID |
| button | string | Yes | V1, V2, V3, or V4 |
| wait_for_result | bool | No | Wait for completion |

Returns: `{ new_image_id, status, url? }`

### midjourney_get_status

Get the status and result of an image generation.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| image_id | string | Yes | Image ID to check |

Returns: `{ image_id, status, url?, progress?, error? }`

### midjourney_list_images

List recent image generations.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| limit | int | No | Max results (default: 20, max: 100) |
| offset | int | No | Pagination offset |
| status | string | No | Filter by status (pending, in-progress, completed, failed) |

Returns: `{ total, count, offset, images[], has_more }`

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| IMAGINEAPI_URL | Yes | ImagineAPI base URL (e.g., http://localhost:8055) |
| IMAGINEAPI_TOKEN | Yes | API authentication token |

### Client Configuration Examples

#### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
`%APPDATA%\Claude\claude_desktop_config.json` (Windows)

```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 -- uvx midjourney-proxy-mcp
```

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

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

#### Cursor

`~/.cursor/mcp.json`:

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

## Implementation Plan

### Phase 1: Project Setup

1. [ ] Initialize pyproject.toml with dependencies
2. [ ] Create basic project structure
3. [ ] Set up pytest configuration
4. [ ] Create CLAUDE.md for project guidelines

### Phase 2: Core Implementation (TDD)

1. [ ] Write tests for ImagineAPI client
2. [ ] Implement ImagineAPI client (client.py)
3. [ ] Write tests for Pydantic models
4. [ ] Implement models (models.py)
5. [ ] Write tests for server initialization
6. [ ] Implement FastMCP server skeleton (server.py)

### Phase 3: Tools Implementation (TDD)

1. [ ] Write tests for midjourney_imagine
2. [ ] Implement midjourney_imagine
3. [ ] Write tests for midjourney_upscale
4. [ ] Implement midjourney_upscale
5. [ ] Write tests for midjourney_variation
6. [ ] Implement midjourney_variation
7. [ ] Write tests for midjourney_get_status
8. [ ] Implement midjourney_get_status
9. [ ] Write tests for midjourney_list_images
10. [ ] Implement midjourney_list_images

### Phase 4: Documentation

1. [ ] Write README.md
2. [ ] Set up MkDocs configuration
3. [ ] Write installation guide
4. [ ] Write configuration guide
5. [ ] Write tools reference
6. [ ] Generate llms.txt

### Phase 5: Packaging & Release

1. [ ] Finalize pyproject.toml metadata
2. [ ] Test local installation (`pip install -e .`)
3. [ ] Test uvx installation
4. [ ] Publish to PyPI
5. [ ] Create GitHub release

## Dependencies

```toml
[project]
dependencies = [
    "mcp>=1.0.0",
    "httpx>=0.27.0",
    "pydantic>=2.0.0",
    "pydantic-settings>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "pytest-asyncio>=0.24.0",
    "pytest-httpx>=0.30.0",
    "ruff>=0.5.0",
    "mypy>=1.10.0",
]
docs = [
    "mkdocs-material>=9.5.0",
]
```

## ImagineAPI Endpoints Reference

Based on the ImagineAPI Directus REST API:

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /items/images | Create new image generation |
| GET | /items/images/:id | Get image status |
| GET | /items/images | List images |
| POST | /items/images/:id | Update (for upscale/variation) |

### Image Status Flow

```
pending --> in-progress --> completed
                       \--> failed
```

### Request Headers

```
Authorization: Bearer {IMAGINEAPI_TOKEN}
Content-Type: application/json
```

## Error Handling

All tools return actionable error messages:

- `Error: Image not found. Check the image_id is correct.`
- `Error: Rate limit exceeded. Wait before making more requests.`
- `Error: Authentication failed. Check IMAGINEAPI_TOKEN.`
- `Error: ImagineAPI unreachable. Check IMAGINEAPI_URL.`
- `Error: Timeout waiting for image. Use midjourney_get_status to check progress.`

## Sources

- FastMCP: https://github.com/jlowin/fastmcp (21k+ stars)
- MCP Protocol: https://modelcontextprotocol.io/llms-full.txt
- GitHub MCP Server: https://github.com/github/github-mcp-server
- MCP Best Practices: mcp-builder skill reference
