Mealplan MCP

A Model Context Provider (MCP) server for meal planning and grocery list generation.

Quick Start

# Clone the repository
git clone <repository-url>
cd mealplan-mcp

# Set up environment variable for meal plan storage
export MEALPLANPATH="/path/to/meal/plans"

# Install dependencies with uv
uv venv && source .venv/bin/activate
uv pip install -e .

# Run the server
python main.py

Features

• Store and retrieve dish recipes with ingredients and instructions
• Create detailed meal plans for specific dates and meal types
• Manage ignored ingredients that should be excluded from grocery lists
• Generate grocery lists for date ranges with automatic checkboxes
• Full MCP (Model Context Provider) compatibility for AI-driven interfaces

Available Tools

Tool	Description	Example Input
create_mealplan	Creates a meal plan	{"meal_plan": {"date": "2023-05-01", "meal_type": "dinner", "title": "Italian Night", "cook": "Chef", "dishes": [...]}}
store_dish	Stores a dish recipe	{"dish_data": {"name": "Pasta", "ingredients": [...]}}
list_dishes	Lists all stored dishes	{}
list_mealplans_by_date_range	Lists meal plans within a date range	{"date_range": {"start": "2023-06-01", "end": "2023-06-07"}}
export_mealplans_to_pdf	Exports meal plans to a PDF file	{"date_range": {"start": "2023-06-01", "end": "2023-06-07"}}
add_ignored_ingredient	Adds ingredient to ignore list	{"ingredient": "salt"}
get_ignored_ingredients	Gets all ignored ingredients	{}
generate_grocery_list	Creates a grocery list markdown	{"date_range": {"start": "2023-06-01", "end": "2023-06-07"}}

Claude Desktop Setup

To use this MCP server with Claude Desktop, add the following configuration to your claude_desktop_config.json file:

macOS

# Edit the config file
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

# Navigate to the config file location
%APPDATA%\Claude\claude_desktop_config.json

Configuration

Add this server configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "mealplan": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/mealplan-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "MEALPLANPATH": "/path/to/your/meal/plans"
      }
    }
  }
}

Important:

• Replace /path/to/your/mealplan-mcp/main.py with the actual path to your main.py file
• Replace /path/to/your/meal/plans with your desired meal plan storage directory
• Restart Claude Desktop after making changes

Development Setup

Prerequisites

• Python 3.12 or higher
• uv (recommended for dependency management)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd mealplan-mcp
   

2. Set up the environment variable for meal plan storage:

   # macOS/Linux
   export MEALPLANPATH="/path/to/meal/plans"
   
   # Windows Command Prompt
   set MEALPLANPATH=C:\path\to\meal\plans
   
   # Windows PowerShell
   $env:MEALPLANPATH = "C:\path\to\meal\plans"
   

3. Set up the virtual environment:

   # Using uv (recommended)
   uv venv
   source .venv/bin/activate  # On macOS/Linux
   # .venv\Scripts\activate    # On Windows
   
   # Alternative: Using venv (built-in)
   python -m venv .venv
   source .venv/bin/activate  # On macOS/Linux
   # .venv\Scripts\activate    # On Windows
   

4. Install dependencies:

   # For basic usage (recommended)
   uv pip install -e .
   
   # For development (includes testing tools)
   uv pip install -e ".[dev]"
   
   # Alternative: Using pip
   pip install -e .              # Basic usage
   pip install -e ".[dev]"       # Development
   

Running the Application

To start the MCP server:

python main.py

This starts the server using stdio transport, making it compatible with MCP client applications.

Testing

The project includes comprehensive testing with automatic test isolation:

# Run all tests
pytest

# Run with coverage
pytest --cov=mealplan_mcp

# Generate a coverage report
pytest --cov=mealplan_mcp --cov-report=html

# Run specific test categories
pytest tests/mealplan/          # Meal plan tests
pytest tests/dish/              # Dish service tests
pytest tests/renderers/         # Renderer tests

MCP Examples

Using the MCP CLI Tool

The MCP CLI tool allows you to interact with your server directly from the command line:

# In a separate terminal, run your server
python main.py

# In another terminal, start the MCP CLI
mcp dev main.py

Project Structure

mealplan-mcp/
├── main.py                  # Entry point and MCP server definition
├── mealplan_mcp/            # Main application package
│   ├── models/              # Pydantic data models
│   │   ├── dish.py          # Dish model with ingredients and instructions
│   │   ├── ingredient.py    # Ingredient model with validation
│   │   ├── ignored.py       # Ignored ingredients model
│   │   ├── meal_plan.py     # Meal plan model with date validation
│   │   ├── meal_type.py     # Meal type enumerations
│   │   └── nutrient.py      # Nutrient information model
│   ├── renderers/           # Markdown rendering modules
│   │   ├── grocery.py       # Grocery list markdown renderer
│   │   └── mealplan.py      # Meal plan markdown renderer
│   ├── services/            # Business logic services
│   │   ├── dish/            # Dish-related services (store, list)
│   │   ├── grocery/         # Grocery list generation services
│   │   ├── ignored/         # Ignored ingredients services
│   │   └── mealplan/        # Meal plan storage services
│   └── utils/               # Utility functions
│       ├── paths.py         # Path handling with test isolation
│       └── slugify.py       # String slugification utilities
├── tests/                   # Comprehensive test suite (113 tests)
└── docs/                    # Documentation

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin feature-name
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.