Norish MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to the Norish recipe management API.

Connect your LLM client to your personal Norish instance for recipe browsing, meal planning, and grocery list management — all through a standardized MCP interface.

Features

This server exposes the following tools:

Recipes

Tool	Description
`get_recipe`	Get a recipe by ID with ingredients and cooking steps
`list_recipes`	List recipes with optional search and pagination
`create_recipe`	Create a new recipe directly with structured data
`import_recipe_url`	Import a recipe from a URL (parses webpage)
`import_recipe_text`	Import a recipe from pasted text (plain text, JSON-LD, or YAML)

Meal Planning

Tool	Description
`get_today_planned_recipes`	Get planned recipes for today
`get_week_planned_recipes`	Get planned recipes for the current week
`get_month_planned_recipes`	Get planned recipes for the current month
`add_to_plan`	Add a recipe to your meal plan for a specific date and slot
`remove_from_plan`	Remove a planned recipe item from your meal plan

Grocery List

Tool	Description
`grocery_list`	List all items in the shopping list
`grocery_create`	Create a new grocery item
`grocery_mark_done`	Mark a grocery item as done (checked off)
`grocery_mark_undone`	Uncheck a previously checked-off grocery item
`grocery_delete`	Delete a grocery item from the shopping list
`grocery_assign_store`	Assign a grocery item to a specific store

Stores

Tool	Description
`list_stores`	List all stores
`create_store`	Create a new store with name, color, and icon

System

Tool	Description
`health_check`	Check the Norish API health (DB, parser service status)

Prerequisites

Node.js v22+ or Docker Compose
A running Norish instance with API access
Your Norish NORISH_API_KEY (generate from your Norish account settings)

Setup

1. Clone and install dependencies

git clone <this-repo-url>
cd norish-mcp
npm install

2. Configure environment variables

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

cp .env.example .env

Variable	Required	Description
`NORISH_API_URL`	Yes	The URL of your running Norish instance (e.g. `https://meals.nashor.cloud:6002`)
`NORISH_API_KEY`	Yes	Your API key from the Norish instance
`MCP_AUTH_ENABLED`	No (default: `true`)	Set to `"false"` to disable authentication entirely. When enabled, `MCP_API_KEY` is required.
`MCP_API_KEY`	Yes (when auth enabled)	Secret key for authenticating requests to this MCP server. Clients must send it as a `Bearer` token in the `Authorization` header.
`ALLOWED_HOSTS`	No	Comma-separated list of allowed hostnames for DNS rebinding protection (e.g., `"norish-mcp.my.domain"`). Defaults to `['norish-mcp.my.domain']`.
`PORT`	No (default: 3001)	Port the MCP server listens on

3. Build and run

Development mode:

npm run dev

Production build:

npm run build
npm start

The server starts on http://localhost:<PORT> with the MCP endpoint at POST /mcp.

Docker (Recommended)

The easiest way to run this server is with Docker Compose using the official image:

# docker-compose.yml
services:
  norish-mcp:
    image: ghcr.io/kellojo/norish-mcp:latest
    container_name: norish-mcp
    ports:
      - "3001:3001"
    env_file: .env

Create a .env file in the same directory:

NORISH_API_URL=https://your-norish-instance.com:6002
NORISH_API_KEY=your-api-key-here
MCP_API_KEY=your-secret-mcp-key
PORT=3001

Then start it:

docker compose up -d

The server will be available at http://localhost:3001 with the MCP endpoint at POST /mcp.

Running Directly

Pull and run without Docker Compose:

docker pull ghcr.io/kellojo/norish-mcp:latest

docker run -d \
  --name norish-mcp \
  -p 3001:3001 \
  --env-file .env \
  ghcr.io/kellojo/norish-mcp:latest

Building from Source

If you prefer to build locally:

docker compose build
docker compose up -d

Authentication

By default, the server requires a Bearer token on every request:

Authorization: Bearer <MCP_API_KEY>

Requests without a valid token are rejected with a 401 Unauthorized error before reaching the MCP handler. This prevents unauthenticated access when exposing the server publicly.

To disable authentication (e.g., for local-only development), set MCP_AUTH_ENABLED=false in your .env. When disabled, no API key is required and clients can connect without an Authorization header.

Client Configuration

Claude Desktop (via mcp.json)

Add this to your Claude Desktop configuration (mcp.json):

{
  "mcpServers": {
    "norish": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "NORISH_API_URL": "https://your-norish-instance.com:6002",
        "NORISH_API_KEY": "<your-norish-api-key>",
        "MCP_API_KEY": "<your-mcp-api-key>"
      }
    }
  }
}

Other MCP Clients

For HTTP-based clients, point them to the server's endpoint with the auth header:

URL: http://localhost:<PORT>/mcp
Method: POST
Headers: Authorization: Bearer <MCP_API_KEY>, Content-Type: application/json

License

MIT