mcp-fooocus-api 0.1.0
MCP server for Fooocus Stable Diffusion API
License: MIT
Requires Python: >=3.10
Keywords: ai, fooocus, image-generation, mcp, stable-diffusion

# MCP Fooocus API

A Model Context Protocol (MCP) server that provides text-to-image generation capabilities through the Fooocus Stable Diffusion API.

## Features

- **Text-to-Image Generation**: Generate high-quality images from text prompts
- **Intelligent Style Selection**: Automatically selects 1-3 appropriate styles based on your prompt
- **Custom Style Override**: Manually specify styles from 300+ available options
- **Multiple Performance Modes**: Choose between Speed, Quality, and Extreme Speed
- **Configurable Aspect Ratios**: Support for various image dimensions
- **Environment-based Configuration**: Easy API endpoint configuration via `.env` file

## Installation

### Using uv (Recommended)

Install directly from GitHub:
```bash
uv add git+https://github.com/raihan0824/mcp-fooocus-api.git
```

Or install from PyPI (when published):
```bash
uv add mcp-fooocus-api
```

Run with uvx:
```bash
uvx --from git+https://github.com/raihan0824/mcp-fooocus-api.git mcp-fooocus-api
```

### Using pip

```bash
pip install git+https://github.com/raihan0824/mcp-fooocus-api.git
```

Or from PyPI (when published):
```bash
pip install mcp-fooocus-api
```

### Development Installation

```bash
# Clone the repository
git clone https://github.com/raihan0824/mcp-fooocus-api.git
cd mcp-fooocus-api

# Install with uv
uv sync --dev

# Or install with pip
pip install -e ".[dev]"
```

## Configuration

1. Copy the example environment file:
```bash
cp .env.example .env
```

2. Edit the `.env` file to configure your Fooocus API endpoint:
```bash
FOOOCUS_API_URL=http://103.125.100.56:8888/v1/generation/text-to-image
```

## Usage

### Available Tools

The MCP server provides three main tools:

#### 1. `generate_image`
Generate an image using the Fooocus API.

**Parameters:**
- `prompt` (required): Text description of the image to generate
- `performance` (optional): Performance setting - "Speed" (default), "Quality", or "Extreme Speed"
- `custom_styles` (optional): Comma-separated list of custom styles
- `aspect_ratio` (optional): Image dimensions (default: "1024*1024")

**Example:**
```json
{
  "prompt": "A serene landscape with mountains and a lake at sunset",
  "performance": "Quality",
  "aspect_ratio": "1024*1024"
}
```

#### 2. `list_available_styles`
Lists all available styles organized by category.

**Returns:**
- Total number of available styles
- Styles organized by categories (Fooocus, SAI, MRE, Art Styles, etc.)
- Available performance options

#### 3. `get_server_info`
Get information about the server configuration and capabilities.

**Returns:**
- Server version and name
- Configured API endpoint
- Available features
- Performance options

### Style Categories

The server includes 300+ styles organized into categories:

- **Fooocus Styles**: Native Fooocus styles (V2, Enhance, Sharp, etc.)
- **SAI Styles**: Stability AI styles (Photographic, Digital Art, Anime, etc.)
- **Art Styles**: Classical art movements (Renaissance, Impressionist, Cubist, etc.)
- **Photography**: Various photography styles (Film Noir, HDR, Macro, etc.)
- **Game Styles**: Video game-inspired styles (Minecraft, Pokemon, Retro, etc.)
- **Futuristic**: Sci-fi and cyberpunk styles
- **And many more...**

### Intelligent Style Selection

When you don't specify custom styles, the server automatically selects appropriate styles based on your prompt:

- **"renaissance portrait"** → Selects "Artstyle Renaissance"
- **"cyberpunk city"** → Selects "Futuristic Cyberpunk Cityscape"
- **"anime character"** → Selects "SAI Anime"
- **"realistic photo"** → Selects "SAI Photographic"
- **"watercolor painting"** → Selects "Artstyle Watercolor"

## Running the Server

### As an MCP Server

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "fooocus": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/raihan0824/mcp-fooocus-api.git", "mcp-fooocus-api"]
    }
  }
}
```

Or if installed from PyPI:
```json
{
  "mcpServers": {
    "fooocus": {
      "command": "uvx",
      "args": ["mcp-fooocus-api"]
    }
  }
}
```

### Standalone Server

You can also run the server directly:

```bash
# With uv
uvx --from git+https://github.com/raihan0824/mcp-fooocus-api.git mcp-fooocus-api --port 3000 --host localhost

# Or if installed locally
python -m mcp_fooocus_api.server --port 3000 --host localhost
```

## API Response Format

Successful generation returns:

```json
{
  "success": true,
  "prompt": "Your prompt here",
  "selected_styles": ["Style1", "Style2"],
  "performance": "Speed",
  "aspect_ratio": "1024*1024",
  "result": {
    // Fooocus API response data
  }
}
```

Error responses include:

```json
{
  "success": false,
  "error": "Error description",
  "prompt": "Your prompt here",
  "selected_styles": ["Style1", "Style2"]
}
```

## Requirements

- Python 3.8+
- Access to a Fooocus API endpoint
- Internet connection for API requests

## Dependencies

- `mcp` >= 1.0.0
- `httpx` >= 0.27
- `python-dotenv` >= 1.0.0
- `pydantic` >= 2.7.2, < 3.0.0

## Development

To set up for development:

1. Clone the repository
2. Install dependencies: `pip install -e .`
3. Configure your `.env` file
4. Run the server: `python -m mcp_fooocus_api.server`

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions, please visit the [GitHub repository](https://github.com/raihan0824/mcp-fooocus-api).