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

Resources

Performer Resources

Studio Resources

Tag Resources

Tools

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:

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.