Paprika MCP Server
A Model Context Protocol (MCP) server for the Paprika Recipe Manager, allowing AI assistants to search, read, and update recipes.
Features
- Search Recipes: Search across recipe titles, ingredients, categories, directions, and notes with context
- Read Recipes: Get full recipe data including all metadata, ingredients, and directions
- Update Recipes: Safely update recipe fields using find/replace (requires user confirmation)
Prerequisites
- Python 3.10 or higher (Python 3.13 recommended)
- A Paprika account with recipes
- Node.js (for pre-commit hooks, optional)
Quick Start
Run the setup script to install everything and configure credentials:
cd paprika-mcp
./setup.sh
This will:
- Install paprika-mcp with dependencies
- Set up pre-commit hooks (if npm available)
Manual Installation
If you prefer manual setup:
1. Install paprika-recipes
cd ../paprika-recipes
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
deactivate
2. Install paprika-mcp
cd ../paprika-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
3. Configure credentials
Option 1: Interactive setup
source .venv/bin/activate
paprika-mcp setup
Option 2: Manual config file
Create ~/.paprika-mcp/config.json:
{
"email": "your@email.com",
"password": "yourpassword"
}
Set permissions:
chmod 600 ~/.paprika-mcp/config.json
Option 3: Environment variables
export PAPRIKA_EMAIL="your@email.com"
export PAPRIKA_PASSWORD="yourpassword"
Credential Management
The server uses a credential flow designed for MCP stdio transport:
Priority order:
PAPRIKA_EMAILandPAPRIKA_PASSWORDenvironment variables~/.paprika-mcp/config.jsonfile
Note: This server manages credentials independently from the paprika-recipes CLI tool's keyring storage. This simplifies the credential flow for MCP stdio transport where the process is spawned by the AI app.
User-Agent
If you have Paprika for Mac installed, the fork of the paprika-recipes Python package should automatically create a suitable User-Agent string. Otherwise, you might have to set the PAPRIKA_USER_AGENT environment variable or the "user_agent" property in config.json.
Usage
As an MCP Server
Add to your MCP client configuration (e.g., Claude Desktop's ~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"paprika": {
"command": "/Users/yourusername/Developer/paprika-mcp/.venv/bin/paprika-mcp"
}
}
}
Or use environment variables:
{
"mcpServers": {
"paprika": {
"command": "/Users/yourusername/Developer/paprika-mcp/.venv/bin/paprika-mcp",
"env": {
"PAPRIKA_EMAIL": "your@email.com",
"PAPRIKA_PASSWORD": "yourpassword"
}
}
}
}
Available Tools
format_fraction
Format a fraction string to unicode fraction characters. This tool is local-only and doesn't require Paprika server connectivity - useful for testing.
Parameters:
fraction(required): Fraction in the form "numerator/denominator" (e.g., "1/4", " 31 / 200 "), or already formatted unicode
Features:
- Handles already-formatted unicode fractions (returns them as-is)
- Strips whitespace from input
- Converts common fractions to dedicated unicode characters
- Composes complex fractions using superscript/subscript digits
Examples:
{
"fraction": "1/4"
}
Returns: ¼
{
"fraction": " 31 / 200 "
}
Returns: ³¹⁄₂₀₀ (whitespace stripped)
{
"fraction": "¼"
}
Returns: ¼ (already formatted, returned as-is)
Common fractions (1/4, 1/2, 3/4, 1/3, 2/3, etc.) use dedicated Unicode characters. Complex fractions are composed using superscript numerator + fraction slash (⁄) + subscript denominator.
search_recipes
Search for recipes by text across multiple fields.
Parameters:
query(required): Text to search forfields(optional): Array of fields to search in:["name", "ingredients", "categories", "directions", "notes"]context_lines(optional): Number of context lines around matches (default: 2)
Example:
{
"query": "chicken",
"fields": ["name", "ingredients"],
"context_lines": 2
}
read_recipe
Read full recipe data by ID or title.
Parameters:
idortitle(one required): Recipe UUID or exact recipe name
Note: Title matching uses Unicode normalization (NFD), so it works correctly with accented characters regardless of their unicode representation (e.g., "café" will match "café").
Example:
{
"id": "RECIPE-UUID-HERE"
}
or
{
"title": "Chocolate Chip Cookies"
}
User Preferences (Prompts)
You can provide context to the AI about how you want it to work with your recipes by creating a ~/.paprika-mcp/prompt.md file. This will be automatically loaded as a prompt when the MCP server starts.
Example prompt file:
# Recipe Management Preferences
- Always preserve source URLs and attribution
- Prefer metric measurements
- I'm cooking for 2 people typically
- I avoid peanuts (allergy)
- Categorize using: Breakfast, Lunch, Dinner, Desserts, Snacks
See prompt.example.md for a complete template.
update_recipe
Update a recipe field using find/replace.
⚠️ DANGEROUS: This tool modifies recipe data. User confirmation is recommended before execution.
Parameters:
id(required): Recipe UUIDfield(required): Field to update (name, ingredients, directions, notes, etc.)find(required): Text to findreplace(required): Text to replace withregex(optional): Treat find pattern as regex (default: false)
Example:
{
"id": "RECIPE-UUID-HERE",
"field": "ingredients",
"find": "1 cup sugar",
"replace": "3/4 cup sugar"
}
Code Changes and Rebuilding
The package is installed in editable mode (pip install -e .), so:
- ✓ No rebuild needed: Changes to
.pyfiles are immediately available - ⚠️ Restart required: MCP clients cache the stdio process - restart VS Code or your MCP client to pick up changes
- ↻ Reinstall needed: Only for
pyproject.tomlor entry point changes
Force reinstall if needed:
.venv/bin/pip install -e . --force-reinstall --no-deps
Pre-commit Hooks
Pre-commit hooks run automatically via Husky when you commit. They:
- Only run on staged Python files
- Run isort, black, and ruff
- Auto-fix issues and re-stage files
To install hooks manually:
npm install
Security Notes
- Credentials are stored in plain text in
~/.paprika-mcp/config.json - Environment variables (
PAPRIKA_EMAIL,PAPRIKA_PASSWORD) are also supported
License
MIT
Credits
Built on top of paprika-recipes originally by Adam Coddington.