Mealie MCP Server for Agentic AI!

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for Knucklessg1 from gravatar.com Knucklessg1

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Author: Genius
  • Requires: Python <3.14, >=3.11
  • Provides-Extra: mcp , agent , all , test
Classifiers
Report project as malware

Project description

Mealie Mcp

CLI or API | MCP | Agent

PyPI - Version MCP Server PyPI - Downloads GitHub Repo stars GitHub forks GitHub contributors PyPI - License GitHub GitHub last commit (by committer) GitHub pull requests GitHub closed pull requests GitHub issues GitHub top language GitHub language count GitHub repo size GitHub repo file count (file type) PyPI - Wheel PyPI - Implementation

Version: 1.0.1

Overview

Mealie Mcp is a production-grade Agent and Model Context Protocol (MCP) server designed to interface directly with Mealie MCP Server for Agentic AI!.

Key Features

  • Consolidated Action-Routed MCP Tools: Minimizes token overhead and eliminates tool bloat in LLM contexts by grouping methods into optimized, togglable tool modules.
  • Enterprise-Grade Security: Comprehensive support for Eunomia policies, OIDC token delegation, and granular execution context tracking.
  • Integrated Graph Agent: Built-in Pydantic AI agent supporting the Agent Control Protocol (ACP) and standard Web interfaces (AG-UI).
  • Native Telemetry & Tracing: Out-of-the-box OpenTelemetry exports and native Langfuse tracing.

CLI or API

This agent wraps the Mealie MCP Server for Agentic AI! API. You can interact with it programmatically or via its integrated execution entrypoints.

Detailed instructions on how to use the underlying API wrappers, extended schema bindings, and developer SDK references are maintained in docs/index.md.

MCP

This server utilizes dynamic Action-Routed tools to optimize token overhead and maximize IDE compatibility.

Available MCP Tools

Condensed action-routed tools (default — MCP_TOOL_MODE=condensed)

MCP Tool Toggle Env Var Description
mealie_admin ADMINTOOL Manage mealie admin operations.
mealie_app APPTOOL Manage mealie app operations.
mealie_explore EXPLORETOOL Manage mealie explore operations.
mealie_groups GROUPSTOOL Manage mealie groups operations.
mealie_households HOUSEHOLDSTOOL Manage mealie households operations.
mealie_organizer ORGANIZERTOOL Manage mealie organizer operations.
mealie_recipes RECIPESTOOL Manage mealie recipes operations.
mealie_shared SHAREDTOOL Manage mealie shared operations.
mealie_users USERSTOOL Manage mealie users operations.
mealie_utils UTILSTOOL Manage mealie utils operations.

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

247 per-operation tools — one per public API method (click to expand)
MCP Tool Toggle Env Var Description
mealie_add_favorite APITOOL Add Favorite
mealie_add_recipe_ingredients_to_list APITOOL Add Recipe Ingredients To List
mealie_add_single_recipe_ingredients_to_list APITOOL Add Single Recipe Ingredients To List
mealie_bulk_categorize_recipes APITOOL Bulk Categorize Recipes
mealie_bulk_delete_recipes APITOOL Bulk Delete Recipes
mealie_bulk_export_recipes APITOOL Bulk Export Recipes
mealie_bulk_settings_recipes APITOOL Bulk Settings Recipes
mealie_bulk_tag_recipes APITOOL Bulk Tag Recipes
mealie_check_app_config APITOOL Check App Config
mealie_check_email_config APITOOL Check Email Config
mealie_clean_images APITOOL Clean Images
mealie_clean_recipe_folders APITOOL Clean Recipe Folders
mealie_clean_temp APITOOL Clean Temp
mealie_create APITOOL Create Api Token
mealie_create_invite_token APITOOL Create Invite Token
mealie_create_random_meal APITOOL Create Random Meal
mealie_create_recipe_from_html_or_json APITOOL Create Recipe From Html Or Json
mealie_create_recipe_from_image APITOOL Create Recipe From Image
mealie_create_recipe_from_zip APITOOL Create Recipe From Zip
mealie_debug_openai APITOOL Debug Openai
mealie_delete APITOOL Delete Api Token
mealie_delete_admin_backups_file_name APITOOL Delete One
mealie_delete_admin_groups_item_id APITOOL Delete One
mealie_delete_admin_households_item_id APITOOL Delete One
mealie_delete_admin_users_item_id APITOOL Delete One
mealie_delete_foods_item_id APITOOL Delete One
mealie_delete_groups_labels_item_id APITOOL Delete One
mealie_delete_groups_reports_item_id APITOOL Delete One
mealie_delete_households_cookbooks_item_id APITOOL Delete One
mealie_delete_households_events_notifications_item_id APITOOL Delete One
mealie_delete_households_mealplans_item_id APITOOL Delete One
mealie_delete_households_mealplans_rules_item_id APITOOL Delete One
mealie_delete_households_recipe_actions_item_id APITOOL Delete One
mealie_delete_households_shopping_items APITOOL Delete Many
mealie_delete_households_shopping_items_item_id APITOOL Delete One
mealie_delete_households_shopping_lists_item_id APITOOL Delete One
mealie_delete_households_webhooks_item_id APITOOL Delete One
mealie_delete_organizers_categories_item_id APITOOL Delete One
mealie_delete_organizers_tools_item_id APITOOL Delete One
mealie_delete_recipe_image APITOOL Delete Recipe Image
mealie_delete_recipe_tag APITOOL Delete Recipe Tag
mealie_delete_recipes_slug APITOOL Delete One
mealie_delete_recipes_timeline_events_item_id APITOOL Delete One
mealie_delete_shared_recipes_item_id APITOOL Delete One
mealie_delete_units_item_id APITOOL Delete One
mealie_download_file APITOOL Download File
mealie_duplicate_one APITOOL Duplicate One
mealie_email_invitation APITOOL Email Invitation
mealie_forgot_password APITOOL Forgot Password
mealie_generate_token APITOOL Generate Token
mealie_get_admin_backups APITOOL Get All
mealie_get_admin_backups_file_name APITOOL Get One
mealie_get_admin_groups APITOOL Get All
mealie_get_admin_groups_item_id APITOOL Get One
mealie_get_admin_households APITOOL Get All
mealie_get_admin_households_item_id APITOOL Get One
mealie_get_admin_users APITOOL Get All
mealie_get_admin_users_item_id APITOOL Get One
mealie_get_all_empty APITOOL Get All Empty
mealie_get_all_households APITOOL Get All Households
mealie_get_app_info APITOOL Get App Info
mealie_get_app_statistics APITOOL Get App Statistics
mealie_get_app_theme APITOOL Get App Theme
mealie_get_comments APITOOL Get All
mealie_get_comments_item_id APITOOL Get One
mealie_get_empty_tags APITOOL Get Empty Tags
mealie_get_explore_groups_group_slug_cookbooks APITOOL Get All
mealie_get_explore_groups_group_slug_cookbooks_item_id APITOOL Get One
mealie_get_explore_groups_group_slug_foods APITOOL Get All
mealie_get_explore_groups_group_slug_foods_item_id APITOOL Get One
mealie_get_explore_groups_group_slug_households APITOOL Get All
mealie_get_explore_groups_group_slug_organizers_categories APITOOL Get All
mealie_get_explore_groups_group_slug_organizers_categories_item_id APITOOL Get One
mealie_get_explore_groups_group_slug_organizers_tags APITOOL Get All
mealie_get_explore_groups_group_slug_organizers_tags_item_id APITOOL Get One
mealie_get_explore_groups_group_slug_organizers_tools APITOOL Get All
mealie_get_explore_groups_group_slug_organizers_tools_item_id APITOOL Get One
mealie_get_explore_groups_group_slug_recipes APITOOL Get All
mealie_get_explore_groups_group_slug_recipes_suggestions APITOOL Suggest Recipes
mealie_get_exported_data APITOOL Get Exported Data
mealie_get_exported_data_token APITOOL Get Exported Data Token
mealie_get_favorites APITOOL Get Favorites
mealie_get_foods APITOOL Get All
mealie_get_foods_item_id APITOOL Get One
mealie_get_group_member APITOOL Get Group Member
mealie_get_group_members APITOOL Get Group Members
mealie_get_group_preferences APITOOL Get Group Preferences
mealie_get_groups_labels APITOOL Get All
mealie_get_groups_labels_item_id APITOOL Get One
mealie_get_groups_reports APITOOL Get All
mealie_get_groups_reports_item_id APITOOL Get One
mealie_get_household APITOOL Get Household
mealie_get_household_members APITOOL Get Household Members
mealie_get_household_preferences APITOOL Get Household Preferences
mealie_get_household_recipe APITOOL Get Household Recipe
mealie_get_households_cookbooks APITOOL Get All
mealie_get_households_cookbooks_item_id APITOOL Get One
mealie_get_households_events_notifications APITOOL Get All
mealie_get_households_events_notifications_item_id APITOOL Get One
mealie_get_households_mealplans APITOOL Get All
mealie_get_households_mealplans_item_id APITOOL Get One
mealie_get_households_mealplans_rules APITOOL Get All
mealie_get_households_mealplans_rules_item_id APITOOL Get One
mealie_get_households_recipe_actions APITOOL Get All
mealie_get_households_recipe_actions_item_id APITOOL Get One
mealie_get_households_shopping_items APITOOL Get All
mealie_get_households_shopping_items_item_id APITOOL Get One
mealie_get_households_shopping_lists APITOOL Get All
mealie_get_households_shopping_lists_item_id APITOOL Get One
mealie_get_households_webhooks APITOOL Get All
mealie_get_households_webhooks_item_id APITOOL Get One
mealie_get_invite_tokens APITOOL Get Invite Tokens
mealie_get_logged_in_user APITOOL Get Logged In User
mealie_get_logged_in_user_favorites APITOOL Get Logged In User Favorites
mealie_get_logged_in_user_group APITOOL Get Logged In User Group
mealie_get_logged_in_user_household APITOOL Get Logged In User Household
mealie_get_logged_in_user_rating_for_recipe APITOOL Get Logged In User Rating For Recipe
mealie_get_logged_in_user_ratings APITOOL Get Logged In User Ratings
mealie_get_maintenance_summary APITOOL Get Maintenance Summary
mealie_get_one_household APITOOL Get One Household
mealie_get_organizers_categories APITOOL Get All
mealie_get_organizers_categories_item_id APITOOL Get One
mealie_get_organizers_categories_slug_category_slug APITOOL Get One By Slug
mealie_get_organizers_tags APITOOL Get All
mealie_get_organizers_tags_item_id APITOOL Get One
mealie_get_organizers_tags_slug_tag_slug APITOOL Get One By Slug
mealie_get_organizers_tools APITOOL Get All
mealie_get_organizers_tools_item_id APITOOL Get One
mealie_get_organizers_tools_slug_tool_slug APITOOL Get One By Slug
mealie_get_ratings APITOOL Get Ratings
mealie_get_recipe APITOOL Get Recipe
mealie_get_recipe_as_format APITOOL Get Recipe As Format
mealie_get_recipe_asset APITOOL Get Recipe Asset
mealie_get_recipe_comments APITOOL Get Recipe Comments
mealie_get_recipe_formats_and_templates APITOOL Get Recipe Formats And Templates
mealie_get_recipe_img APITOOL Get Recipe Img
mealie_get_recipe_timeline_event_img APITOOL Get Recipe Timeline Event Img
mealie_get_recipes APITOOL Get All
mealie_get_recipes_slug APITOOL Get One
mealie_get_recipes_suggestions APITOOL Suggest Recipes
mealie_get_recipes_timeline_events APITOOL Get All
mealie_get_recipes_timeline_events_item_id APITOOL Get One
mealie_get_shared_recipe APITOOL Get Shared Recipe
mealie_get_shared_recipe_as_zip APITOOL Get Shared Recipe As Zip
mealie_get_shared_recipes APITOOL Get All
mealie_get_shared_recipes_item_id APITOOL Get One
mealie_get_startup_info APITOOL Get Startup Info
mealie_get_statistics APITOOL Get Statistics
mealie_get_storage APITOOL Get Storage
mealie_get_storage_details APITOOL Get Storage Details
mealie_get_todays_meals APITOOL Get Todays Meals
mealie_get_token APITOOL Get Token
mealie_get_units APITOOL Get All
mealie_get_units_item_id APITOOL Get One
mealie_get_user_image APITOOL Get User Image
mealie_get_validation_text APITOOL Get Validation Text
mealie_import_one APITOOL Import One
mealie_logout APITOOL Logout
mealie_oauth_callback APITOOL Oauth Callback
mealie_oauth_login APITOOL Oauth Login
mealie_parse_ingredient APITOOL Parse Ingredient
mealie_parse_ingredients APITOOL Parse Ingredients
mealie_parse_recipe_url APITOOL Parse Recipe Url
mealie_parse_recipe_url_bulk APITOOL Parse Recipe Url Bulk
mealie_patch_many APITOOL Patch Many
mealie_patch_one APITOOL Patch One
mealie_post_admin_backups APITOOL Create One
mealie_post_admin_groups APITOOL Create One
mealie_post_admin_households APITOOL Create One
mealie_post_admin_users APITOOL Create One
mealie_post_comments APITOOL Create One
mealie_post_foods APITOOL Create One
mealie_post_groups_labels APITOOL Create One
mealie_post_households_cookbooks APITOOL Create One
mealie_post_households_events_notifications APITOOL Create One
mealie_post_households_mealplans APITOOL Create One
mealie_post_households_mealplans_rules APITOOL Create One
mealie_post_households_recipe_actions APITOOL Create One
mealie_post_households_shopping_items APITOOL Create One
mealie_post_households_shopping_items_create_bulk APITOOL Create Many
mealie_post_households_shopping_lists APITOOL Create One
mealie_post_households_webhooks APITOOL Create One
mealie_post_organizers_categories APITOOL Create One
mealie_post_organizers_tags APITOOL Create One
mealie_post_organizers_tools APITOOL Create One
mealie_post_parser_ingredient APITOOL Delete One
mealie_post_recipes APITOOL Create One
mealie_post_recipes_timeline_events APITOOL Create One
mealie_post_shared_recipes APITOOL Create One
mealie_post_units APITOOL Create One
mealie_purge_export_data APITOOL Purge Export Data
mealie_put_admin_groups_item_id APITOOL Update One
mealie_put_admin_households_item_id APITOOL Update One
mealie_put_admin_users_item_id APITOOL Update One
mealie_put_comments_item_id APITOOL Update One
mealie_put_foods_item_id APITOOL Update One
mealie_put_foods_merge APITOOL Merge One
mealie_put_groups_labels_item_id APITOOL Update One
mealie_put_households_cookbooks APITOOL Update Many
mealie_put_households_cookbooks_item_id APITOOL Update One
mealie_put_households_events_notifications_item_id APITOOL Update One
mealie_put_households_mealplans_item_id APITOOL Update One
mealie_put_households_mealplans_rules_item_id APITOOL Update One
mealie_put_households_recipe_actions_item_id APITOOL Update One
mealie_put_households_shopping_items APITOOL Update Many
mealie_put_households_shopping_items_item_id APITOOL Update One
mealie_put_households_shopping_lists_item_id APITOOL Update One
mealie_put_households_webhooks_item_id APITOOL Update One
mealie_put_organizers_categories_item_id APITOOL Update One
mealie_put_organizers_tags_item_id APITOOL Update One
mealie_put_organizers_tools_item_id APITOOL Update One
mealie_put_recipes APITOOL Update Many
mealie_put_recipes_slug APITOOL Update One
mealie_put_recipes_timeline_events_item_id APITOOL Update One
mealie_put_units_item_id APITOOL Update One
mealie_put_units_merge APITOOL Merge One
mealie_refresh_token APITOOL Refresh Token
mealie_register_new_user APITOOL Register New User
mealie_remove_favorite APITOOL Remove Favorite
mealie_remove_recipe_ingredients_from_list APITOOL Remove Recipe Ingredients From List
mealie_request BASE_API_CLIENTTOOL Invoke the request operation.
mealie_rerun_webhooks APITOOL Rerun Webhooks
mealie_reset_password APITOOL Reset Password
mealie_scrape_image_url APITOOL Scrape Image Url
mealie_seed_foods APITOOL Seed Foods
mealie_seed_labels APITOOL Seed Labels
mealie_seed_units APITOOL Seed Units
mealie_send_test_email APITOOL Send Test Email
mealie_set_member_permissions APITOOL Set Member Permissions
mealie_set_rating APITOOL Set Rating
mealie_start_data_migration APITOOL Start Data Migration
mealie_test_notification APITOOL Test Notification
mealie_test_one APITOOL Test One
mealie_test_parse_recipe_url APITOOL Test Parse Recipe Url
mealie_trigger_action APITOOL Trigger Action
mealie_unlock_users APITOOL Unlock Users
mealie_update_event_image APITOOL Update Event Image
mealie_update_group_preferences APITOOL Update Group Preferences
mealie_update_household_preferences APITOOL Update Household Preferences
mealie_update_label_settings APITOOL Update Label Settings
mealie_update_last_made APITOOL Update Last Made
mealie_update_password APITOOL Update Password
mealie_update_recipe_image APITOOL Update Recipe Image
mealie_update_user APITOOL Update User
mealie_update_user_image APITOOL Update User Image
mealie_upload_one APITOOL Upload One
mealie_upload_recipe_asset APITOOL Upload Recipe Asset

10 action-routed tool(s) (default) · 247 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (condensed default · verbose 1:1 · both). Auto-generated — do not edit.

Detailed tool schemas, parameter shapes, and validation constraints are preserved in docs/mcp.md.

Dynamic Tool Selection & Visibility

This MCP server supports dynamic toolset selection and visibility filtering at runtime. This allows you to restrict the set of exposed tools in order to prevent blowing up the LLM's context window.

You can configure tool filtering via multiple input channels:

  • CLI Arguments: Pass --tools or --toolsets (or their disabled counterparts --disabled-tools and --disabled-toolsets) during startup.
  • Environment Variables: Define standard environment variables:
    • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS
    • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS
  • HTTP SSE Request Headers: Pass custom headers during transport initialization:
    • x-mcp-enabled-tools / x-mcp-disabled-tools
    • x-mcp-enabled-tags / x-mcp-disabled-tags
  • HTTP SSE Request Query Parameters: Append query parameters directly to your transport connection URL:
    • ?tools=tool1,tool2
    • ?tags=tag1

When query strings or parameters are supplied, an LLM-free Knowledge Graph resolution layer (using DynamicToolOrchestrator) matches query intents against known tool tags, names, or descriptions, with safe fallback and automated 24-hour background cache refreshing.

MCP Configuration Examples

Install the slim [mcp] extra. All examples install mealie-mcp[mcp] — the MCP-server extra that pulls only the FastMCP / FastAPI tooling (agent-utilities[mcp]). It deliberately excludes the heavy agent runtime (pydantic-ai, the epistemic-graph engine, dspy, llama-index), so uvx / container installs are far smaller. Use the full [agent] extra only when you need the integrated Pydantic AI agent.

stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "mealie-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "mealie-mcp[mcp]",
        "mealie-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "condensed",
        "ADMINTOOL": "True",
        "APPTOOL": "True",
        "EXPLORETOOL": "True",
        "GROUPSTOOL": "True",
        "HOUSEHOLDSTOOL": "True",
        "MEALIE_BASE_URL": "http://localhost:8025",
        "MEALIE_TOKEN": "your_token_here",
        "ORGANIZERTOOL": "True",
        "RECIPESTOOL": "True",
        "SHAREDTOOL": "True",
        "USERSTOOL": "True",
        "UTILSTOOL": "True"
      }
    }
  }
}

Streamable-HTTP Transport (networked / production)

{
  "mcpServers": {
    "mealie-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "mealie-mcp[mcp]",
        "mealie-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "0.0.0.0",
        "PORT": "8000",
        "MCP_TOOL_MODE": "condensed",
        "ADMINTOOL": "True",
        "APPTOOL": "True",
        "EXPLORETOOL": "True",
        "GROUPSTOOL": "True",
        "HOUSEHOLDSTOOL": "True",
        "MEALIE_BASE_URL": "http://localhost:8025",
        "MEALIE_TOKEN": "your_token_here",
        "ORGANIZERTOOL": "True",
        "RECIPESTOOL": "True",
        "SHAREDTOOL": "True",
        "USERSTOOL": "True",
        "UTILSTOOL": "True"
      }
    }
  }
}

Alternatively, connect to a pre-deployed Streamable-HTTP instance by url:

{
  "mcpServers": {
    "mealie-mcp": {
      "url": "http://localhost:8000/mealie-mcp/mcp"
    }
  }
}

Deploying the Streamable-HTTP server via Docker:

docker run -d \
  --name mealie-mcp-mcp \
  -p 8000:8000 \
  -e TRANSPORT=streamable-http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e MCP_TOOL_MODE=condensed \
  -e ADMINTOOL=True \
  -e APPTOOL=True \
  -e EXPLORETOOL=True \
  -e GROUPSTOOL=True \
  -e HOUSEHOLDSTOOL=True \
  -e MEALIE_BASE_URL=http://localhost:8025 \
  -e MEALIE_TOKEN=your_token_here \
  -e ORGANIZERTOOL=True \
  -e RECIPESTOOL=True \
  -e SHAREDTOOL=True \
  -e USERSTOOL=True \
  -e UTILSTOOL=True \
  knucklessg1/mealie-mcp:mcp

Auto-generated from the code-read env surface (MCP_TOOL_MODE + package vars) — do not edit.

Additional Deployment Options

mealie-mcp can also run as a local container (Docker / Podman / uv) or be consumed from a remote deployment. The Deployment guide has full, copy-paste mcp_config.json for all four transports — stdio, streamable-http, local container / uv, and remote URL:

  • Local container / uv — launch the server from mcp_config.json via uvx, docker run, or podman run, or point at a local streamable-http container by url.
  • Remote URL — connect to a server deployed behind Caddy at http://mealie-mcp.arpa/mcp using the "url" key.

Agent

This repository features a fully integrated Pydantic AI Graph Agent. It communicates over the Agent Control Protocol (ACP) and interacts seamlessly with the Agent Web UI (AG-UI) and Terminal interface.

Running the Agent CLI

To start the interactive command-line agent:

# Set credentials
export MEALIE_BASE_URL="your_value"
export MEALIE_TOKEN="your_value"
export MEALIE_SSL_VERIFY="False"

# Run the agent server
mealie-agent --provider openai --model-id gpt-4o

Docker Compose Orchestration

The following docker/agent.compose.yml configures the Agent, Web UI, and Terminal Interface together:

version: '3.8'

services:
  mealie-mcp-mcp:
    image: knucklessg1/mealie-mcp:latest
    container_name: mealie-mcp-mcp
    hostname: mealie-mcp-mcp
    restart: always
    env_file:
      - ../.env
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=8000
      - TRANSPORT=streamable-http
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  mealie-mcp-agent:
    image: knucklessg1/mealie-mcp:latest
    container_name: mealie-mcp-agent
    hostname: mealie-mcp-agent
    restart: always
    depends_on:
      - mealie-mcp-mcp
    env_file:
      - ../.env
    command: [ "mealie-agent" ]
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=9013
      - MCP_URL=http://mealie-mcp-mcp:8000/mcp
      - PROVIDER=${PROVIDER:-openai}
      - MODEL_ID=${MODEL_ID:-gpt-4o}
      - ENABLE_WEB_UI=True
      - ENABLE_OTEL=True
    ports:
      - "9013:9013"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9013/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Detailed graph node architecture explanations, custom skill configurations, and agentic trace guides are available in docs/agent.md.

Security & Governance

Built directly upon the enterprise-ready agent-utilities core, standard security parameters are fully supported:

Access Control & Policy Enforcement

  • Eunomia Policies: Fine-grained, policy-driven tool authorization. Supports none, local embedded (mcp_policies.json), or centralized remote modes.
  • OIDC Token Delegation: Compliant with RFC 8693 token exchange for flowing authenticating user credentials from Web UI / ACP → Agent → MCP.
  • Scoped Credentials: Execution context runs restricted to the specific caller identity.

Runtime Security Grid

Feature Functionality Enablement
Tool Guard Sensitivity inspection with human-in-the-loop validation Enabled by default
Prompt Injection Defense Input scanning, repetition monitoring, and recursive loop blocks Enabled by default
Context Safety Guard Stuck-loop detectors and contextual overflow preemptive alerts Enabled by default

Environment Variables

Package environment variables

Variable Example Description
HOST 0.0.0.0
PORT 8000
TRANSPORT stdio options: stdio, streamable-http, sse
ENABLE_OTEL True
OTEL_EXPORTER_OTLP_ENDPOINT http://localhost:8080/api/public/otel
OTEL_EXPORTER_OTLP_PUBLIC_KEY pk-...
OTEL_EXPORTER_OTLP_SECRET_KEY sk-...
OTEL_EXPORTER_OTLP_PROTOCOL http/protobuf
EUNOMIA_TYPE none options: none, embedded, remote
EUNOMIA_POLICY_FILE mcp_policies.json
EUNOMIA_REMOTE_URL http://eunomia-server:8000
MEALIE_BASE_URL http://localhost:8025 Base URL of your Mealie instance
MEALIE_TOKEN your_token_here Mealie API token
MEALIE_SSL_VERIFY False verify TLS certs when calling Mealie
APPTOOL True
USERSTOOL True
HOUSEHOLDSTOOL True
GROUPSTOOL True
RECIPESTOOL True
ORGANIZERTOOL True
SHAREDTOOL True
ADMINTOOL True
EXPLORETOOL True
UTILSTOOL True

Inherited agent-utilities variables (apply to every connector)

Variable Example Description
MCP_TOOL_MODE condensed Tool surface: condensed
MCP_ENABLED_TOOLS — Comma-separated tool allow-list
MCP_DISABLED_TOOLS — Comma-separated tool deny-list
MCP_ENABLED_TAGS — Comma-separated tag allow-list
MCP_DISABLED_TAGS — Comma-separated tag deny-list
MCP_CLIENT_AUTH — Outbound MCP auth (oidc-client-credentials for fleet calls)
OIDC_CLIENT_ID — OIDC client id (service-account auth)
OIDC_CLIENT_SECRET — OIDC client secret (service-account auth)
DEBUG False Verbose logging
PYTHONUNBUFFERED 1 Unbuffered stdout (recommended in containers)
MCP_URL http://localhost:8000/mcp URL of the MCP server the agent connects to
PROVIDER openai LLM provider for the agent
MODEL_ID gpt-4o Model id for the agent
ENABLE_WEB_UI True Serve the AG-UI web interface

24 package + 14 inherited variable(s). Auto-generated from .env.example + the shared agent-utilities set — do not edit.

Every variable the server reads. A local template is supplied inside .env.example — copy it to .env and fill in your endpoint/credentials.

Connection & Credentials

Variable Description Default
MEALIE_BASE_URL Base URL of your Mealie instance http://localhost:8025
MEALIE_TOKEN Mealie API token —
MEALIE_SSL_VERIFY Verify TLS certs when calling Mealie False

MCP server / transport

Variable Description Default
TRANSPORT stdio, streamable-http, or sse stdio
HOST Bind host (HTTP transports) 0.0.0.0
PORT Bind port (HTTP transports) 8000
MCP_TOOL_MODE Tool surface: condensed, verbose, or both condensed
MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS Comma-separated tool allow/deny list —
MCP_ENABLED_TAGS / MCP_DISABLED_TAGS Comma-separated tag allow/deny list —
PYTHONUNBUFFERED Unbuffered stdout (recommended in containers) 1

Telemetry & governance

Variable Description Default
ENABLE_OTEL Enable OpenTelemetry export True
OTEL_EXPORTER_OTLP_ENDPOINT OTLP collector endpoint —
OTEL_EXPORTER_OTLP_PUBLIC_KEY / OTEL_EXPORTER_OTLP_SECRET_KEY OTLP auth keys —
OTEL_EXPORTER_OTLP_PROTOCOL OTLP protocol (e.g. http/protobuf) —
EUNOMIA_TYPE Authorization mode: none, embedded, remote none
EUNOMIA_POLICY_FILE Embedded policy file mcp_policies.json
EUNOMIA_REMOTE_URL Remote Eunomia server URL —

Tool toggles

Each action-routed tool can be disabled individually via its toggle env var (set to false). The full list is in the Available MCP Tools table above (e.g. RECIPESTOOL, USERSTOOL, ORGANIZERTOOL, ADMINTOOL).

Agent CLI (full [agent] runtime only)

Variable Description Default
MCP_URL URL of the MCP server the agent connects to http://localhost:8000/mcp
PROVIDER LLM provider (e.g. openai) openai
MODEL_ID Model id (e.g. gpt-4o) gpt-4o
ENABLE_WEB_UI Serve the AG-UI web interface True

Installation

Pick the extra that matches what you want to run:

Extra Installs Use when
mealie-mcp[mcp] Slim MCP server only (agent-utilities[mcp] — FastMCP/FastAPI) You only run the MCP server (smallest install / image)
mealie-mcp[agent] Full agent runtime (agent-utilities[agent,logfire] — Pydantic AI + the epistemic-graph engine) You run the integrated agent
mealie-mcp[all] Everything (mcp + agent + logfire) Development / both surfaces 
# MCP server only (recommended for tool hosting — slim deps)
uv pip install "mealie-mcp[mcp]"

# Full agent runtime (Pydantic AI + epistemic-graph engine)
uv pip install "mealie-mcp[agent]"

# Everything (development)
uv pip install "mealie-mcp[all]"      # or: python -m pip install "mealie-mcp[all]"

Container images (:mcp vs :agent)

One multi-stage docker/Dockerfile builds two right-sized images, selected by --target:

Image tag Build target Contents Entrypoint
knucklessg1/mealie-mcp:mcp --target mcp mealie-mcp[mcp] — slim, no engine/pydantic-ai/dspy/llama-index/tree-sitter mealie-mcp
knucklessg1/mealie-mcp:latest --target agent (default) mealie-mcp[agent] — full agent runtime + epistemic-graph engine mealie-agent 
docker build --target mcp   -t knucklessg1/mealie-mcp:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/mealie-mcp:latest docker/   # full agent

docker/mcp.compose.yml runs the slim :mcp server; docker/agent.compose.yml runs the agent (:latest) with a co-located :mcp sidecar.

Knowledge-graph database (epistemic-graph)

The full agent ([agent] / :latest) embeds the epistemic-graph engine (pulled in transitively via agent-utilities[agent]). For production — or to share one knowledge graph across multiple agents — run epistemic-graph as its own database container and point the agent at it instead of embedding it. Deployment recipes (single-node + Raft HA), connection config, and the full database architecture (with diagrams) are documented in the epistemic-graph deployment guide. The slim [mcp] server does not require the database.

Repository Owners

GitHub followers GitHub User's stars

Contribute

Contributions are welcome! Please ensure code quality by executing local checks before submitting pull requests:

  • Format code using ruff format .
  • Lint code using ruff check .
  • Validate type-safety with mypy .
  • Execute test suites using pytest

Deploy with agent-os-genesis

This package can be provisioned for you — skill-guided — by the agent-os-genesis universal skill (its single-package deploy mode): it picks your install method, seeds secrets to OpenBao/Vault (or .env), trusts your enterprise CA, registers the MCP server, and verifies it — the same machinery that stands up the whole Agent OS, narrowed to just this package. Ask your agent to "deploy mealie-mcp with agent-os-genesis".

Install mode Command
Bare-metal, prod (PyPI) uvx mealie-mcp · or uv tool install mealie-mcp
Bare-metal, dev (editable) uv pip install -e ".[all]" · or pip install -e ".[all]"
Container, prod deploy knucklessg1/mealie-mcp:latest via docker-compose / swarm / podman / podman-compose / kubernetes
Container, dev (editable) deploy docker/compose.dev.yml (source-mounted at /src; edits live on restart)

Secrets are read-existing + seeded via vault_sync — you are only prompted for what's missing.

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for Knucklessg1 from gravatar.com Knucklessg1

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Author: Genius
  • Requires: Python <3.14, >=3.11
  • Provides-Extra: mcp , agent , all , test
Classifiers

Release history Release notifications | RSS feed

This version

1.0.1

0.42.0

0.40.0

0.38.0

0.35.0

0.33.4

0.33.0

0.29.0

0.25.0

0.15.0

0.12.1

0.12.0

0.11.0

0.10.0

0.9.0

0.8.1

0.3.0

0.2.57

0.2.55

0.2.54

0.2.48

0.2.46

0.2.45

0.2.42

0.2.41

0.2.40

0.2.33

0.2.32

0.2.29

0.2.28

0.2.26

0.2.25

0.2.24

0.2.23

0.2.22

0.2.21

0.2.20

0.2.19

0.2.18

0.2.17

0.2.16

0.2.15

0.2.14

0.2.13

0.2.12

0.2.11

0.2.10

0.2.9

0.2.8

0.2.7

0.2.6

0.2.5

0.2.4

0.2.2

0.2.1

0.2.0

0.1.3

0.1.2

0.1.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mealie_mcp-1.0.1.tar.gz (63.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mealie_mcp-1.0.1-py3-none-any.whl (61.5 kB view details)

Uploaded Python 3

File details

Details for the file mealie_mcp-1.0.1.tar.gz.

File metadata

  • Download URL: mealie_mcp-1.0.1.tar.gz
  • Upload date:
  • Size: 63.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.4

File hashes

Hashes for mealie_mcp-1.0.1.tar.gz
Algorithm Hash digest
SHA256 17b453ab3f67538a2425e439b2c1cd5edcd7dde97d48ec065f6050b439b71f77
MD5 8600a34b1c65fff28d8925526e44003d
BLAKE2b-256 5f016cd2432f3f74f29cdb326dd3ce2d639ea2dc72991ed6353d50dcc504e450

See more details on using hashes here.

File details

Details for the file mealie_mcp-1.0.1-py3-none-any.whl.

File metadata

  • Download URL: mealie_mcp-1.0.1-py3-none-any.whl
  • Upload date:
  • Size: 61.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.4

File hashes

Hashes for mealie_mcp-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 12cb6d46d87302bd3f2563db427122fd4cd298167f30000e69c5569406b2eb90
MD5 3692f8cd28e4d4937f20ed82de543ef2
BLAKE2b-256 41c95ca73a05ee4f44c3b478996b6f5f94a38e9d21c1c4245cc9ebb5cd6bdcfd

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page