Mealie MCP Server

An MCP (Model Context Protocol) server that connects Claude and other MCP clients to your Mealie recipe manager instance. Search, create, import, and update recipes through natural language.

Features

• Get Recipe — Retrieve full recipe details by slug or ID

• Search Recipes — Free-text search with filtering by category, tag, food, and tool

• Create Recipe — Create recipes from structured data (name, ingredients, instructions, etc.)

• Import Recipe — Import recipes by URL (Mealie scrapes the page automatically)

• Update Recipe — Modify any field on an existing recipe

Related MCP server: Mealie MCP Server

Prerequisites

• Mealie v1+ instance running and accessible

• A Mealie API token (generate at <your-mealie-url>/user/profile/api-tokens)

• Node.js 20+ (for local usage) or Docker

Transports

The server supports two transports:

Authentication

There are two separate auth layers — one for the server to talk to Mealie, and one for clients to talk to the server:

Claude.ai ──OAuth 2.0──▶ MCP Server ──API Token──▶ Mealie

1. Mealie API Token (MEALIE_API_TOKEN) — The server's backend credential for accessing Mealie's REST API. Required for both transports. Generate one at <your-mealie-url>/user/profile/api-tokens.

2. OAuth 2.0 + PKCE (HTTP transport only) — How remote clients like Claude.ai authenticate to the MCP server. Users log in with their Mealie username and password via a browser-based flow. The server validates credentials against Mealie and issues OAuth tokens. Not used with stdio transport.

In short: the API token lets the server access recipes, and OAuth lets users prove who they are.

Configuration

Copy .env.example to .env and fill in your values:

cp .env.example .env

Environment variables

Usage

With Claude Desktop (stdio)

Add to your claude_desktop_config.json:

Using Docker:

{
  "mcpServers": {
    "mealie": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MEALIE_URL",
        "-e", "MEALIE_API_TOKEN",
        "mealie-mcp-server"
      ],
      "env": {
        "MEALIE_URL": "http://your-mealie-instance:9925",
        "MEALIE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Using Node.js directly:

{
  "mcpServers": {
    "mealie": {
      "command": "node",
      "args": ["/path/to/mealie-mcp-server/build/index.js"],
      "env": {
        "MEALIE_URL": "http://your-mealie-instance:9925",
        "MEALIE_API_TOKEN": "your-api-token"
      }
    }
  }
}

With Claude Code (stdio)

claude mcp add mealie -- node /path/to/mealie-mcp-server/build/index.js \
  -e MEALIE_URL=http://your-mealie-instance:9925 \
  -e MEALIE_API_TOKEN=your-api-token

HTTP Transport (Claude.ai web / remote access)

The HTTP transport uses OAuth 2.0 with PKCE, with Mealie credentials as the identity provider. Users authenticate via a login page using their Mealie username and password. This makes it compatible with Claude.ai (web and mobile), which requires OAuth-capable MCP servers.

Requirements: The server must be reachable at a public HTTPS URL (MCP_SERVER_URL).

Using Node.js:

MEALIE_URL=http://your-mealie:9925 \
MEALIE_API_TOKEN=your-api-token \
MCP_SERVER_URL=https://mcp.your-domain.com \
node build/http.js

Using Docker:

docker run --rm \
  -p 3000:3000 \
  -e TRANSPORT=http \
  -e MEALIE_URL=http://your-mealie:9925 \
  -e MEALIE_API_TOKEN=your-api-token \
  -e MCP_SERVER_URL=https://mcp.your-domain.com \
  mealie-mcp-server

Using Docker Compose:

# Set env vars in .env file, then:
docker compose up mealie-mcp-server-http

Connecting Claude.ai to the HTTP endpoint:

In Claude.ai settings, add a new MCP server pointing at https://mcp.your-domain.com/mcp. Claude.ai will discover the OAuth metadata automatically and prompt you to log in with your Mealie credentials.

Nginx configuration:

See nginx-mcp.conf.example for the location blocks needed to proxy MCP and OAuth traffic when running behind nginx.

A health check endpoint is available at GET /health.

Note on auth state: The HTTP server stores OAuth tokens in memory. Restarting the server invalidates all existing sessions and requires clients to re-authenticate.

Tools

get_recipe

Get a recipe by its slug or ID.

search_recipes

Search and list recipes with optional filters.

create_recipe

Create a recipe from structured data.

import_recipe

Import a recipe by URL. Mealie scrapes the page and extracts recipe data.

update_recipe

Update fields on an existing recipe. Only provided fields are changed.

Development

Setup

npm install

Build

npm run build

Run in development

# stdio transport
MEALIE_URL=http://localhost:9925 MEALIE_API_TOKEN=your-token npm run dev

# HTTP transport
MEALIE_URL=http://localhost:9925 MEALIE_API_TOKEN=your-token \
MCP_SERVER_URL=http://localhost:3000 npm run dev:http

Test

npm test

# With coverage
npm run test:coverage

# Watch mode
npm run test:watch

Docker

# Build the image
docker build -t mealie-mcp-server .

# Run (stdio)
docker run -i --rm \
  -e MEALIE_URL=http://your-mealie:9925 \
  -e MEALIE_API_TOKEN=your-token \
  mealie-mcp-server

# Run (HTTP with OAuth)
docker run --rm -p 3000:3000 \
  -e TRANSPORT=http \
  -e MEALIE_URL=http://your-mealie:9925 \
  -e MEALIE_API_TOKEN=your-token \
  -e MCP_SERVER_URL=https://mcp.your-domain.com \
  mealie-mcp-server

Architecture

src/
├── index.ts              # stdio entry point
├── http.ts               # HTTP entry point (Streamable HTTP transport + OAuth)
├── server.ts             # Creates MCP server and registers all tools (transport-agnostic)
├── mealie-client.ts      # HTTP client for the Mealie REST API
├── types.ts              # TypeScript type definitions for Mealie API shapes
├── auth/
│   ├── provider.ts       # OAuth 2.0 provider (validates Mealie credentials, issues tokens)
│   └── login-page.ts     # HTML login page rendered during OAuth authorization flow
└── tools/
    ├── get-recipe.ts     # get_recipe tool
    ├── search-recipes.ts # search_recipes tool
    ├── create-recipe.ts  # create_recipe tool
    ├── import-recipe.ts  # import_recipe tool
    └── update-recipe.ts  # update_recipe tool

The server core (server.ts) is transport-agnostic — it builds the MCP server and registers tools without knowing which transport will be used. The two entry points (index.ts for stdio, http.ts for HTTP) each wire in their respective transport.

• stdio communicates via stdin/stdout using JSON-RPC 2.0. Standard for Claude Desktop and local MCP clients.

• Streamable HTTP exposes a /mcp endpoint supporting POST (requests), GET (SSE stream), and DELETE (session termination). Uses stateful sessions with Mcp-Session-Id headers. Full OAuth 2.0 + PKCE authentication using Mealie credentials as the identity provider.

License

MIT