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

1. Python 3.10 or higher (Python 3.13 recommended)

2. A Paprika account with recipes

3. 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:

1. Install paprika-mcp with dependencies

2. 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:

1. PAPRIKA_EMAIL and PAPRIKA_PASSWORD environment variables

2. ~/.paprika-mcp/config.json file

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 for

• fields (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:

• id or title (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 UUID

• field (required): Field to update (name, ingredients, directions, notes, etc.)

• find (required): Text to find

• replace (required): Text to replace with

• regex (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 .py files 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.toml or 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:

1. Only run on staged Python files

2. Run isort, black, and ruff

3. 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.