Stash MCP Server

An MCP (Model Context Protocol) server that provides a concise set of tools to query and analyze an Stash instance with composable, high‑precision filters, optimized caching for faster queries, automated intelligence for performer/scene analysis, and personalized recommendations based on usage and preferences.

Prompts

Prompt	Description	Parameters
analyze-performer	Complete performer analysis with insights	performer_name: str
library-insights	Strategic insights for the entire library	—
recommend-scenes	Personalized scene recommendations	preferences: str
discover-performers	Performer discovery by criteria	criteria: str

Resources

Performer Resources

Resource	Description	URI
All performers	List of all favorite performers with basic info	stash://performer/all
Performers Information	Detailed information about a specific performer	stash://performer/{name}
Performers by Country	List of performers filtered by country	stash://performer/country/{country}
Performers by Ethnicity	List of performers filtered by ethnicity	stash://performer/ethnicity/{ethnicity}
Performers Statistics	Statistical summary of all performers	stash://performer/stats

Studio Resources

Resource	Description	URI
All studios	List of all favorite studios with basic info	stash://studio/all
Studio Information	Detailed information about a specific studio	stash://studio/{name}
Studios Statistics	Statistical summary of all studios	stash://studio/stats

Tag Resources

Resource	Description	URI
All tags	List of all favorite tags with basic info	stash://tag/all
Tag Information	Detailed information about a specific tag	stash://tag/{name}
Tags Statistics	Statistical summary of all tags	stash://tag/stats

Tools

Tool	Description	Parameters
advanced_performer_analysis	Deep analysis with progress and logging	performer_name: str, include_similar: bool, deep_scene_analysis: bool
batch_performer_insights	Aggregated insights from multiple performers	performer_names: List[str], max_performers: int
health_check	Basic connectivity/cache status	—
get_performer_info	Detailed performer information	performer_name: str
get_all_performers	List performers with advanced filtering	favorites_only: bool=True, advanced filters (see "Advanced Filters" section)
get_all_scenes_from_performer	Scenes for a performer	performer_name: str, organized_only: bool=True
get_all_scenes	List all scenes with optional filters	advanced filters (see "Advanced Filters" section)

Advanced Filters for get_all_performers

This tool now supports advanced filtering by multiple physical and demographic criteria:

Basic Filters

• favorites_only: bool = True - Limit to favorite performers
• country: str - Filter by country
• ethnicity: str - Filter by ethnicity
• eye_color: str - Filter by eye color
• hair_color: str - Filter by hair color
• measurements: str - Filter by body measurements
• piercings: str - Filter by piercings
• tattoos: str - Filter by tattoos

Numeric Filters with Modifiers

• height_cm: int - Filter by height in centimeters
• weight: int - Filter by weight

Filter Modifiers

Each filter supports modifiers for different comparison types:

• EQUALS (default) - Exact match
• NOT_EQUALS - Not equal
• GREATER_THAN - Greater than (numeric only)
• LESS_THAN - Less than (numeric only)
• BETWEEN - Between two values (numeric only, requires _value2)
• NOT_BETWEEN - Not between two values (numeric only, requires _value2)

Range Parameters

For BETWEEN and NOT_BETWEEN filters:

• height_cm_value2: int - Second value for height range
• weight_value2: int - Second value for weight range

Resources for performers information

The server provides dedicated resources to access performers information in multiple formats:

Resource URIs

• stash://performer/all - Lists all favorite performers with basic information

  • Returns: Name, country, ethnicity, height, weight, and associated tags
  • Use case: Get a quick overview of all favorite performers

• stash://performer/{name} - Detailed information for a specific performer

  • Parameters: {name} - Exact performer name
  • Returns: Complete profile including demographics, physical characteristics, bio, and tags
  • Use case: Get comprehensive information about a specific performer

• stash://performer/country/{country} - Filter performers by country

  • Parameters: {country} - Country name or code (e.g., "USA", "ES")
  • Returns: List of performers from the specified country with ethnicity
  • Use case: Discover performers from a specific country

• stash://performer/ethnicity/{ethnicity} - Filter performers by ethnicity

  • Parameters: {ethnicity} - Ethnicity name (e.g., "Caucasian", "Asian")
  • Returns: List of performers with the specified ethnicity and their countries
  • Use case: Find performers matching specific ethnic characteristics

• stash://performer/stats - Statistical summary of the performer database

  • Returns:
    • Total number of favorite performers
    • Geographic distribution (countries and counts)
    • Ethnic distribution
    • Physical statistics (average height and weight ranges)
  • Use case: Analyze the composition and diversity of your performer collection

Configuration

The server supports flexible configuration through environment variables:

Variable	Default	Description
STASH_ENDPOINT	http://localhost:6969	Stash server endpoint
STASH_API_KEY	—	Required API key (mandatory)
STASH_CONNECT_RETRIES	3	Initial connection retries
STASH_CONNECT_DELAY_SECONDS	1.5	Delay between retries (seconds)
FAVORITES	true	Filter resources by favorites only
LOG_LEVEL	INFO	Log level: DEBUG, INFO, WARNING, ERROR

Environment Setup

1. Copy the example environment file:

cp .env.example .env

2. Edit .env with your settings:

STASH_ENDPOINT=http://localhost:9999
STASH_API_KEY=YOUR_API_KEY

Installation

Install with uv (recommended)

Clone the repository and install with uv:

git clone https://github.com/donlothario/stash_mcp_server.git
cd stash_mcp_server
cp .env.example .env
# Edit .env file with your Stash settings
uv sync

Or install directly from the repository:

uv add git+https://github.com/donlothario/stash_mcp_server.git

Install with pip

Install the package in mode:

git clone https://github.com/donlothario/stash_mcp_server.git
cd stash_mcp_server
cp .env.example .env
# Edit .env file with your Stash settings
python3 -m pip install .

Or install directly from the repository:

python3 -m pip install git+https://github.com/donlothario/stash_mcp_server.git

Docker

Build the image

Build the image:

docker build -t stash_mcp_server:latest .

Pull the image

Pull the latest image from the Docker registry:

docker pull ghcr.io/donlothario/stash_mcp_server:latest

Usage

Running with uv

uv run stash_mcp_server

Running with pip installation

python3 -m stash_mcp_server

Configuration example for Claude Desktop/Cursor/VSCode

Add this configuration to your application's settings (mcp.json):

Using uv (recommended)

"stash mcp server": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/stash_mcp_server",
      "stash_mcp_server"
    ],
    "env": {
        "STASH_ENDPOINT": "http://localhost:9999",
        "STASH_API_KEY": "YOUR_API_KEY",
    }
}

Using pip installation

"stash mcp server": {
    "type": "stdio",
    "command": "python3",
    "args": [
        "-m",
        "stash_mcp_server"
    ],
    "env": {
        "STASH_ENDPOINT": "http://localhost:9999",
        "STASH_API_KEY": "YOUR_API_KEY",
    }
}

Using Docker

"stash mcp server": {
    "type": "stdio",
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "${workspaceFolder}/.env",
        "ghcr.io/donlothario/stash_mcp_server"
    ]
}

Technical Notes

• Connection to Stash is performed with configurable retries.
• If the API key is missing, the server generates an error and does not start.
• GraphQL fragments used by queries are centralized in the code (FRAGMENTS).
• Improved cache architecture: Cache functions are separated from MCP decorators to avoid conflicts with Pydantic schema generation.
• Advanced filtering: Robust filter system with modifiers and range handling for complex queries.
• Enhanced logging: Detailed information about active filters and query results for better debugging.