npm package: @schaferandrew/mealie-mcp-server
Description: MCP server for integrating Mealie recipe manager with Claude and Vivian
Latest version: 0.1.3

# Mealie MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects your AI assistant to your [Mealie](https://mealie.io) self-hosted recipe manager.

Once connected, you can ask Claude things like:
- "What recipes do I have with pasta?"
- "Show me all my chicken recipes"
- "Import this recipe from the URL: ..."
- "What recipes use cream cheese?"

## Prerequisites

- **Node.js** 18 or later
- A running **Mealie** instance (v1.0+ recommended)
- A **Mealie API key** (see below)

## Getting Your Mealie API Key

1. Open your Mealie instance in a browser
2. Click your profile icon → **Profile**
3. Scroll to the **API Tokens** section
4. Click **Create API Token**, give it a name (e.g. `claude`), and click **Generate**
5. **Copy the token immediately** — it won't be shown again

## Installation

No installation required — run directly with `npx`:

```bash
npx @schaferandrew/mealie-mcp-server
```

Or install globally if you prefer:

```bash
npm install -g @schaferandrew/mealie-mcp-server
```

## Claude Desktop Setup

Add the server to your Claude Desktop config file:

**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mealie": {
      "command": "npx",
      "args": ["-y", "@schaferandrew/mealie-mcp-server"],
      "env": {
        "MEALIE_URL": "http://your-mealie-instance:9000",
        "MEALIE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Restart Claude Desktop — you should see the Mealie tools available in Claude.

## Claude Code Setup

```bash
claude mcp add mealie -- npx -y @schaferandrew/mealie-mcp-server \
  -e MEALIE_URL=http://your-mealie-instance:9000 \
  -e MEALIE_API_KEY=your-api-key-here
```

Add `--scope global` to make it available in all projects.

## Available Tools

| Tool | Description |
|---|---|
| `search_recipes` | Search recipes by name or keyword.<br>Example: `search_recipes pasta` |
| `get_recipe` | Get full recipe details including ingredients & instructions.<br>Example: `get_recipe "Spaghetti Carbonara"` |
| `list_recipes` | List all recipes, optionally filtered by tag or category.<br>Example: `list_recipes tag=vegetarian` |
| `add_recipe_from_url` | Import a recipe by scraping a URL.<br>Example: `add_recipe_from_url https://example.com/recipe` |
| `search_by_ingredient` | Find recipes containing a specific ingredient.<br>Example: `search_by_ingredient chicken` |

## Configuration

| Environment Variable | Required | Description |
|---|---|---|
| `MEALIE_URL` | Yes | Base URL of your Mealie instance (e.g. `http://localhost:9000`) |
| `MEALIE_API_KEY` | Yes | API token generated in your Mealie profile |

## Security Notes

- API keys are never logged — credentials are redacted from all error messages
- Never hardcode credentials; use environment variables
- `.env` is gitignored — `.env.example` is safe to commit

## Development

Clone the repo and install dependencies:

```bash
git clone https://github.com/schaferandrew/mealie-mcp-server.git
cd mealie-mcp-server
npm install
npm run build
```

Test your Mealie connection:

```bash
MEALIE_URL=http://your-instance MEALIE_API_KEY=your-key npm run test-connection
```

### Releasing a New Version

Releases are published to npm automatically when a GitHub Release is published.

**Step 1 — bump the version and open a PR:**

```bash
# Pick one based on the nature of your changes:
npm version patch --no-git-tag-version   # 0.1.0 → 0.1.1  (bug fixes)
npm version minor --no-git-tag-version   # 0.1.0 → 0.2.0  (new features)
npm version major --no-git-tag-version   # 0.1.0 → 1.0.0  (breaking changes)

VERSION=$(node -p "require('./package.json').version")

git checkout -b release/v$VERSION
git add package.json package-lock.json
git commit -m "chore: bump version to $VERSION"
git push -u origin release/v$VERSION
gh pr create --title "chore: release v$VERSION" --body "Version bump to v$VERSION." --base main
```

**Step 2 — after the PR is merged, create the GitHub Release:**

```bash
# Make sure you're on main with the latest changes
git checkout main && git pull origin main

VERSION=$(node -p "require('./package.json').version")

gh release create "v$VERSION" \
  --title "v$VERSION" \
  --generate-notes
```

GitHub Actions will publish to npm automatically.

> **Note:** `NPM_TOKEN` must be set in your repo under **Settings → Secrets and variables → Actions**. Requires the [GitHub CLI](https://cli.github.com) (`gh`).

## License

MIT