Stash
MCP server that exposes advanced tools for querying a Stash instance.
What is Stash?
Stash is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to mcp server that exposes advanced tools for querying a stash instance.
MCP server that exposes advanced tools for querying a Stash instance.
This server falls under the Browser Automation category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- MCP server that exposes advanced tools for querying a Stash
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx stash-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Stash
Stash MCP Server exposes advanced querying tools for a self-hosted Stash instance (the open-source media management application) through the Model Context Protocol. It provides high-precision, composable filters for performers and scenes including demographic attributes, physical characteristics, and numeric comparisons. The server supports optimized caching, multiple install methods (uv, pip, Docker), and connection retry logic, making it suitable for both personal use and production deployments where reliable AI-assisted media library queries are needed.
Prerequisites
- A running Stash instance accessible over HTTP (default port 6969)
- A Stash API key generated from Stash Settings > Security
- Python 3.11 or later, or Docker, for running the MCP server
- uv package manager recommended (pip also supported)
Clone the repository
Clone the Stash MCP Server repository. No PyPI package is published, so installation is from source.
git clone https://github.com/donlothario/stash_mcp_server.git
cd stash_mcp_serverConfigure environment variables
Copy the example environment file and set your Stash endpoint URL and API key. STASH_API_KEY is mandatory; all other variables have defaults.
cp .env.example .env
# Edit .env and set:
# STASH_ENDPOINT=http://localhost:6969
# STASH_API_KEY=your_stash_api_key
# FAVORITES=true
# LOG_LEVEL=INFOInstall with uv (recommended)
Use uv to resolve and install Python dependencies. This is the method recommended by the project maintainer.
uv syncRun the server
Start the MCP server using uv. It will connect to your Stash instance and expose the query tools over stdio for MCP clients.
uv run stash_mcp_serverAlternative: run with Docker
For a containerized deployment, pull the pre-built image and pass environment variables at runtime.
docker run -it --rm \
-e STASH_ENDPOINT=http://host.docker.internal:6969 \
-e STASH_API_KEY=your_stash_api_key \
ghcr.io/donlothario/stash_mcp_server:latestAdd to Claude Desktop configuration
Register the server in claude_desktop_config.json using the uv run command so Claude Desktop manages the process lifecycle.
{
"mcpServers": {
"stash": {
"command": "uv",
"args": ["run", "stash_mcp_server"],
"cwd": "/path/to/stash_mcp_server",
"env": {
"STASH_ENDPOINT": "http://localhost:6969",
"STASH_API_KEY": "your_stash_api_key"
}
}
}
}Stash Examples
Client configuration
Claude Desktop configuration using uv to launch the Stash MCP server with connection credentials supplied as environment variables.
{
"mcpServers": {
"stash": {
"command": "uv",
"args": ["run", "stash_mcp_server"],
"cwd": "/Users/yourname/stash_mcp_server",
"env": {
"STASH_ENDPOINT": "http://localhost:6969",
"STASH_API_KEY": "your_api_key_here",
"FAVORITES": "true",
"LOG_LEVEL": "INFO"
}
}
}
}Prompts to try
These prompts exercise the high-precision filtering and analysis tools exposed by the server.
- "Run a health check on the Stash connection and confirm caching is working."
- "Get all performers from the US with brown eyes and return their scene counts."
- "Show me scenes from a specific performer sorted by rating, filtering to favorites only."Troubleshooting Stash
Connection refused when server starts
Confirm your Stash instance is running and accessible at the STASH_ENDPOINT URL. If running Stash in Docker, use 'host.docker.internal' instead of 'localhost' as the hostname when running the MCP server in a container.
Authentication error: 401 Unauthorized
Regenerate your API key in Stash under Settings > Security > API Keys. Paste the new key into your .env file and restart the server. Ensure no trailing whitespace is included in the key value.
uv command not found
Install uv with 'curl -LsSf https://astral.sh/uv/install.sh | sh' on macOS/Linux. Alternatively, use pip: 'pip install .' from the repository root, then run with 'python3 -m stash_mcp_server'.
Frequently Asked Questions about Stash
What is Stash?
Stash is a Model Context Protocol (MCP) server that mcp server that exposes advanced tools for querying a stash instance. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Stash?
Follow the installation instructions on the Stash GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Stash?
Stash works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Stash free to use?
Yes, Stash is open source and available under the Apache-2.0 license. You can use it freely in both personal and commercial projects.
Stash Alternatives — Similar Browser Automation Servers
Looking for alternatives to Stash? Here are other popular browser automation servers you can use with Claude, Cursor, and VS Code.
Chrome DevTools MCP
★ 40.6kAI-powered Chrome automation server with natural language element detection. Control Chrome browser through MCP protocol for testing, debugging, and performance analysis. Features 91% accuracy in element location, works with free AI models, and suppo
UI TARS Desktop
★ 34.9k📇 🏠 - Browser automation capabilities using Puppeteer, both support local and remote browser connection.
Playwright
★ 32.8kA production-ready browser automation server that enables AI assistants to interact with web pages using tools for navigation, element interaction, and data extraction. It features a built-in Inspector UI and robust crash recovery for reliable automa
Page Agent
★ 18.0kJavaScript in-page GUI agent. Control web interfaces with natural language.
Chrome
★ 11.7kAn extension-based MCP server that enables AI assistants to control your browser, leveraging existing sessions and login states for automation and content analysis. It provides over 20 tools for semantic tab search, interactive element manipulation,
LAMDA
★ 7.8kThe most powerful Android RPA agent framework, next generation mobile automation.
Browse More Browser Automation MCP Servers
Explore all browser automation servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Stash in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Stash?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.