# Civitai MCP Server (Python FastMCP)

A Python FastMCP implementation of an MCP server for interacting with the Civitai API. Browse AI models, images, creators, and more.

## Features

- **Model Search**: Search AI models with various filters
- **Model Details**: Get detailed information about specific models
- **Image Browsing**: Browse AI-generated images
- **Creator Search**: Search for model creators
- **Tag Search**: Search models by tags
- **Popular/Latest/Top Rated**: Get ranking information
- **FastMCP Resources**: Structured resource definitions for models, versions, images, creators, and tags

## Installation

1. Install dependencies:
```bash
pip install -r requirements.txt
```

2. Set up environment variables (optional):
```bash
cp .env.example .env
# Edit .env file to set your Civitai API key
```

## Usage

### Standalone Execution
```bash
python civitai_mcp_server.py
```

### Docker Execution

#### Option 1: Use Pre-built Image from Docker Hub
```bash
docker run -d --name civitai-mcp-server -p 8000:8000 -e CIVITAI_API_KEY=your_api_key_here waura/civitai-mcp-server:latest
```

#### Option 2: Build Locally
1. Build the Docker image:
```bash
docker build -t civitai-mcp-server .
```

2. Run the container:
```bash
docker run -d --name civitai-mcp-server -p 8000:8000 -e CIVITAI_API_KEY=your_api_key_here civitai-mcp-server
```

3. Access the MCP server at `http://localhost:8000/mcp`

4. Stop the container:
```bash
docker stop civitai-mcp-server
docker rm civitai-mcp-server
```

### Deploy your MCP server to Amazon Bedrock AgentCore

Deploy using [Amazon Bedrock AgentCore starter toolkit](https://github.com/aws/bedrock-agentcore-starter-toolkit)

```
agentcore configure -e civitai_mcp_server.py --protocol MCP
```

```
agentcore launch 
```

### MCP Configuration

#### For Standalone Python Execution

Add the following to your Kiro configuration file (`.kiro/settings/mcp.json`):

```json
{
  "mcpServers": {
    "civitai": {
      "command": "python",
      "args": ["path/to/civitai_mcp_server.py"],
      "env": {
        "CIVITAI_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

#### For Docker Execution

**Option 1: HTTP Transport (推奨)**

Add the following to your Kiro configuration file (`.kiro/settings/mcp.json`):

```json
{
  "mcpServers": {
    "civitai": {
      "transport": "http",
      "url": "http://localhost:8000/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

**Option 2: Docker Command (Pre-built Image)**

```json
{
  "mcpServers": {
    "civitai": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-p", "8000:8000",
        "-e", "CIVITAI_API_KEY=your_api_key_here",
        "waura/civitai-mcp-server:latest"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

**Option 3: Docker Command (Local Build)**

```json
{
  "mcpServers": {
    "civitai": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-p", "8000:8000",
        "-e", "CIVITAI_API_KEY=your_api_key_here",
        "civitai-mcp-server"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

**Option 4: curl Command**

```json
{
  "mcpServers": {
    "civitai": {
      "command": "curl",
      "args": ["-X", "POST", "http://localhost:8000/mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

## Available Tools

### Model-related
- `search_models`: Search models with query, type, sort filters
- `get_model`: Get detailed model information by ID
- `get_model_version`: Get model version details
- `get_model_version_by_hash`: Get model version by file hash
- `get_popular_models`: Get popular models
- `get_latest_models`: Get newest models
- `get_top_rated_models`: Get highest rated models
- `search_models_by_tag`: Search models by tag
- `search_models_by_creator`: Search models by creator
- `get_models_by_type`: Filter models by type
- `get_download_url`: Get download URL

### Other
- `get_images`: Get images
- `get_creators`: Search creators
- `get_tags`: Search tags

## FastMCP Resources

This server also provides structured resource definitions that can be accessed via FastMCP resource URIs:

### Model Resources
- `civitai://models/{limit}` - List models with filtering options (limit parameter required)
- `civitai://models/{model_id}` - Get specific model details

### Model Version Resources
- `civitai://model-versions/{version_id}` - Get model version details
- `civitai://model-versions/by-hash/{hash}` - Get model version by file hash

### Image Resources
- `civitai://images/{limit}` - List images with filtering options (limit parameter required)

### Creator Resources
- `civitai://creators/{limit}` - List creators (limit parameter required)

### Tag Resources
- `civitai://tags/{limit}` - List tags (limit parameter required)

These resources provide structured data models that can be used programmatically by MCP clients.

## API Key

A Civitai API key is not required but recommended for:
- Access to private models
- Higher rate limits
- Some advanced features

You can get an API key from your [Civitai](https://civitai.com) account settings.

## Examples

```python
# Search models
search_models(query="anime", limit=10, sort="Most Downloaded")

# Get specific model details
get_model(model_id=12345)

# Get popular LORA models
get_models_by_type(type="LORA", sort="Most Downloaded", limit=5)

# Get images
get_images(limit=20, nsfw="None", sort="Newest")
```

## Notes

- API responses can be large
- Use NSFW filtering options appropriately
- Store API keys securely using environment variables