# 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
