Civitai Server

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:

pip install -r requirements.txt

2. Set up environment variables (optional):

cp .env.example .env
# Edit .env file to set your Civitai API key

Usage

Standalone Execution

python civitai_mcp_server.py

Docker Execution

Option 1: Use Pre-built Image from Docker Hub

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:

docker build -t civitai-mcp-server .

2. Run the container:

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:

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

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):

{
  "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):

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

Option 2: Docker Command (Pre-built Image)

{
  "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)

{
  "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

{
  "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 account settings.

Examples

# 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