Free and open source · Runs on your server

Dinner, planned.The pantry, counted.The list, sent.

Merran is a meal planner for your household that runs on your own server, with an optional AI cooking assistant. Import recipes, plan the week, track pantry amounts, and send shopping lists to supported store carts when connected.

Install with Docker View on GitHub
AGPL-3.0 Docker Compose Optional AI, your provider or endpoint Phone, iPad and desktop
Interactive preview · sample data Sage & Cream
192.168.1.20:3000
5:42

Good evening, Sam

Thursday, October 15

AI photo

Tonight · Dinner

Chicken + Rice with Peanut Sauce

4 servings35 minOn the list

Already home: rice and garlic.

Also today · Breakfast: Overnight Oats (done)

This week

12 of 14 planned

Saturday's dinner is open

Shopping

14 to buy · about $79

Chicken thighs, paneer and limes

Use soon

Spinach

Tomorrow, and 3 more

Coming up

Plan

Tomorrow

Saag Paneer

Dinner · Meatless night

Saturday

Nothing planned

Plan it

Sunday

Lemon Ricotta Pancakes

Breakfast

Cook again

Miso Salmon

Made Sep 30

Creamy Tomato Soup

Made Sep 21

Thai Basil Chicken

Made Sep 28

Bring the weekly routine together

Keep recipes, plans and shopping connected, with optional AI when you want a hand.

  • Work with your own recipe library.The optional assistant can read household records and propose kitchen changes for you to approve.
  • Keep track of what is already home.Record amounts, use-by dates and food reserved for a planned meal. Comparable quantities can be deducted.
  • Review products before sending a list.Connect an eligible Kroger-family account to add products to its cart. Checkout stays with the retailer.
  • Make use of available nutrition data.Keep imported nutrition, calculate with a USDA key, or use optional AI estimates. Coverage varies by ingredient.

How it fits together

One loop, every week. AI when you want it.

Choose meals, add their ingredients to the list, and account for pantry stock. Put purchases away, then mark planned meals cooked to deduct their recorded stock. Optional AI can help along the way.

Recipes, then Plan, then Shop, then Cook, around the assistant 1 Recipes 2 Plan 3 Shop 4 Cook Assistant sees all of it

1 · Recipes

Recipes from the places you find them

Import a recipe page or type one in. Optional AI reads pasted text, photos and PDFs; video imports also need the video module. Review the result before planning dinner. Read the Recipes guide →

Importing recipes

6 of 10
Birria Tacostiktok.com · read from the captionsAdded
Miso-Glazed Salmonbonappetit.comAdded
Lemon Ricotta Pancakesyoutube.com · read from the videoAdded
Reading the video…instagram.com/reel/C9xQ…Importing
Black Bean Tacosbudgetbytes.comAlready had
Waitingsmittenkitchen.com/2024/10/…Waiting

A batch imports one link at a time in a server job. It carries on after you close the page; individual links can fail or be skipped.

Moving from Mealie? Import a backup or export under Settings → Import and export → From another app. Direct connection also requires server-admin access. Read the migration guide →

2 · Plan

A week that fills itself, if you want it to

Fill the week suggests meals from your library without AI. Tastes, recent meals and time limits shape the choices; pantry stock and available price data can influence them. Review before adding. Keep flexible meals in the week's Any day pool, or repeat last week into empty slots. Read the Planning guide →

Fill the week

Next week, Oct 18 – 24 · ideas for the 4 open dinners

    Sample suggestions; recent meals influence real results.

    Try the sample re-roll and add controls. Real suggestions prefer matching themes and available pantry stock; neither is guaranteed.

    3 · Shop

    Shop for what you don't have. Then put it away.

    Combine recognized quantities, account for pantry stock, and check purchases off together. Put away checked food to update the pantry. Store connections are optional; checkout stays with the retailer. Read the Shopping and pantry guide →

    Add from the plan

    Oct 18 – 24 · 5 meals aren't on the list yet

    • Beef StewSun · 6 servings
    • Creamy Tomato SoupMon · 4 servings
    • Fish TacosTue · 4 servings
    • Miso SalmonWed · 4 servings
    • Spicy RigatoniSat · 6 servings

    18 things go on the list

    Amounts add up across recipes: 1 onion + 2 onions is 3 onions.

    Left off, because you have them

    Rice · 2 lbGarlicSoy sauceLimes · 2Parmesan · half a block

    Always on hand

    SaltPepperOlive oil
    CancelAdd 18 things

    Grouped by aisle, with configured weekly items included. Assign items to stores yourself; the example split is not an automatic retailer decision.

    4 · Cook

    Made for a phone propped on the counter

    Big steps, ingredient checklists, and timers from recognized durations. Screen wake lock and hands-free commands depend on your browser. Read the Cooking guide →

    Try the sample steps, timers and checklists. Voice commands and saved notes are simulated here; no microphone or AI provider is used.

    In the middle · Assistant

    An assistant that knows your kitchen

    Scripted conversations, not live AI responses. Example approvals only change this preview.

    Set up optional AI → · What leaves your server →

    It's available throughout the signed-in app, and it can see your recipes, plan, pantry and list. It starts with your library, searches the web when you ask when the model supports it, and offers cards for you to approve proposed kitchen changes. How proposals work →

    • Review proposed changes. Apply or dismiss kitchen changes from the assistant. Requests and background features have their own processing and saving steps.
    • Anthropic, OpenAI, Google, or a compatible endpoint, with household or shared server keys and model choices per task.
    • Conversations are kept, so you can pick one up again on another device.
    Assistant
    Ask anything about cooking

    And the rest

    The small things that add up

    Useful details, grouped by where they fit. Open a collection to explore.

    01Your cookbookLabels, units, pairings and a little room to change your mind.6 details

    Diet labels, worked out

    Ingredient-based labels with explanations and corrections. Check ingredients yourself; labels are not allergy guarantees. Recipe labels →

    Grams for baking

    Convert recognized foods and quantities to metric or US units, using food-specific weights when available. Scaling and units →

    Goes with

    Mix and match sauces and sides, so “chicken + rice” isn't saved a hundred times over. Recipe pairings →

    Select, then act

    Select recipes, meals or list items for supported bulk actions. Undo is available for supported changes, not every operation. Organize recipes →

    Recently deleted

    Recipes can be restored from Recently deleted before cleanup after 30 days. Restoring a recipe does not promise to recreate removed plan entries. Recipe recovery →

    Recipe versions

    Inspect earlier saved versions and go back to one while keeping the current version in history. Editing recipes →

    02Your everyday kitchenNutrition, costs and the people you cook with.6 details

    Nutrition with sources

    Imported values, USDA calculations with a key, or optional AI estimates. Daily plan totals depend on recipe coverage and servings. Nutrition requirements →

    What it costs

    Estimated recipe costs from known product prices. A weekly budget influences suggestions; it is not a spending cap. Prices and budgets →

    Several households

    Yours and your parents', each with its own recipes, plan and list, on one server. Household roles →

    A voice like a person

    Use device speech, run optional Kokoro on your infrastructure, or configure paid OpenAI speech. Browser support and voice availability vary. Voice setup →

    Three palettes

    Sage & Cream, Paprika & Linen, or Cast Iron & Saffron, in light or dark. Try them up top. First-run setup →

    Shop together

    Connected household devices refresh when the list or plan changes, with presence indicators on those pages. Shared shopping →

    03Make it your ownImport, connect and add optional AI when it helps.6 details

    Browser extension

    Import readable content from the page you have open. Requires extension setup and site access; experimental Walmart cart filling is optional. Import methods →

    Share to Merran

    Use a supported Android share sheet or set up an iPhone Shortcut. AI and video requirements still apply; receipts wait for review before pantry changes. Share and import →

    Bring recipes with you

    Import supported Mealie or Paprika files, and export a Merran household archive for portability. Keep a separate full-server backup. Backups and recovery →

    An API for your tools

    Create scoped API keys and use the generated endpoint reference to build integrations. API quickstart →

    Review recipe improvements

    Optional AI Tidy up proposes changes for you to inspect and apply. Review and approvals →

    Optional recipe photos

    Generate images for recipes without a photo in a household style. Off by default; eligible OpenAI or Google access and provider charges apply. AI requirements →

    Coming from Mealie?

    Compare the workflows, then try a migration

    Both projects cover recipes, planning and shopping. Merran connects those with measured pantry stock, optional store carts and an assistant that proposes changes. Mealie also has AI imports and a broad integration system; those are not unique to Merran.

    Move recipes from Mealie

    Settings → Import and export → From another app. Household admins can import supported files; a direct connection also requires server-admin access.

    Photos and recipe metadata depend on the source export. Review the import summary and sample recipes; this is a migration, not ongoing synchronization.

    Migration steps →
    Selected workflows · documentation reviewed October 17, 2026
    Workflow Mealie documentation Merran implementation
    Recipe entry Website and manual entry; AI imports from URLs, videos, images and text Website and manual entry; optional AI for text/photos/PDFs and video extraction
    Meal planning Calendar, per-meal servings, notes and planner rules Per-meal servings, theme preferences, Fill the week and optional scheduled planning without AI
    Shopping Recipe-linked lists, editable quantities and labels Combined quantities, pantry deductions, purchase put-away and optional supported store connections
    Households Isolated groups; households within a group share recipes Separate household recipes, plans, lists and pantry; owner/admin/member roles
    Integrations API, notifiers, webhooks and recipe actions Scoped API keys, generated API docs, share intake and browser extension
    Backups Built-in system backup management Household export for portability; server backup and restore managed by the operator

    Sources: Mealie's official feature guide and AI setup; Merran's implementation-audited guides. This is a selected comparison, not a complete feature inventory or a claim about a particular released version. Merran release verification is still pending.

    Self-hosted

    One file and a docker compose up

    The build targets Linux AMD64 and ARM64 Docker hosts. The default app container uses SQLite; Postgres is supported as a separate database service. Application data is stored on your server; optional external services receive the content they process. Saved provider keys are not returned to the browser. Read about data flow →

    • MerranThe web app, API and SQLite support in one image, listening on port 3000 by default.
    • SQLite, or PostgresBack up the app data and secret; Postgres also needs a consistent database backup. Migrations run on startup.
    • KokoroOptionalSelf-hosted speech for cook mode. Enable --profile voice and configure the Kokoro address in Settings.
    • Cloudflare TunnelOptionalOptional remote access without inbound port forwarding. Configure a tunnel, hostname and token, then enable --profile tunnel.
    • UpdatesAn Update badge in Settings when a new release is out, with its notes and the commands for your setup. 
    # On your server
$ mkdir merran && cd merran
$ curl -fsSLO https://raw.githubusercontent.com/merran-app/merran/main/compose.yaml
$ docker compose up -d
# Open http://<your-server>:3000. The setup code is in the log:
$ docker compose logs merran

    These commands follow the development configuration. Confirm an available release tag before installing; a fresh-release installation has not yet been verified. Installation details → · Backups and recovery →

    What the AI costs

    Your provider or endpoint determines the bill. Merran shows estimated usage, not a live invoice; limits are not a guaranteed billing cap. Manual recipes, structured page imports, planning, lists and pantry tracking work without AI. Understand costs and limits →

    Make a photo for a recipe that has none Provider image charges
    Find a recipe online with the assistant Model usage and search charges
    Discover with AI Depends on searches and reading
    Read a whole recipe aloud in OpenAI's voice Depends on text and provider pricing
    Read it aloud with Kokoro Your hosting costs; no OpenAI reading charge

    Open source

    Open source and self-hosted.

    Merran is free software under the GNU AGPL v3. You run the application and create accounts on your own server. Hosting and optional external services can have their own costs.

    Read the repository license for the terms governing use, modification and sharing.
    With supplied Compose, app files and SQLite live in ./data/app. Postgres may be local or external; back up its database too.
    Built in the open. Issues, ideas and pull requests are welcome.
    Do I need an AI key?

    AI features need an eligible provider key or compatible endpoint. Core recipes, planning, lists and pantry tracking work without AI; media features can have additional provider requirements. See the feature requirements →

    What does it run on?

    The container build targets Linux AMD64 and ARM64. Verify the image and requirements for your chosen release. Memory needs depend on workload and optional services; no measured minimum is published here.

    Is there a phone app?

    Merran is a web app. Supported browsers can install it on the home screen over HTTPS. Android sharing depends on browser support; iPhone sharing requires a Shortcut you configure in Settings. This does not promise offline operation.

    Can my whole family use it?

    Yes. Invite each person with a link and they make their own account. One server can host several households too, each kept separate. Households can use their own AI credentials when policy permits, or eligible shared server keys. Recorded-usage limits are not hard billing caps. Roles and permissions →

    Which stores can it send the list to?

    Eligible Kroger-family stores use a configured developer app and linked household account. Other stores, including Costco, use search links. Walmart cart filling is an opt-in extension experiment. Availability varies; checkout happens at the retailer.

    How do I move from Mealie?

    Open Settings → Import and export → From another app. Household admins can import a backup or recipe export; a server admin who also administers the destination household can connect with Mealie's address and an API token. Re-import skips known recipes rather than syncing edits. Follow the migration guide →

    Can I reach it away from home?

    Configure a tunnel, VPN or HTTPS reverse proxy, then set the public URL and trusted proxies for your deployment. Household data requires authorization, but setup, sign-in and some public endpoints are accessible before login. Follow the configuration guide before exposing the server.

    Cook something good tonight.

    Set it up this afternoon, move your recipes over, and let it plan next week.

    Read the install guideStar it on GitHub