Meals MCP Server

A production-ready Model Context Protocol server for discovering and retrieving meal recipes. Powered by the free TheMealDB API.

What It Does

Meals MCP provides AI assistants with 5 powerful tools for meal discovery and recipe lookup:

• Search meals by name
• Find random meals for inspiration
• Browse meals by category (Seafood, Vegetarian, Pasta, etc.)
• Filter meals by ingredient
• Get full recipes with ingredients, measurements, and instructions

No authentication required. All data comes from the free, public TheMealDB API.

Quick Start

Installation

npm install
npm run build

Start the Server

npm start

The MCP server will start on stdio transport and wait for client connections.

Available Tools

1. search_meal

Search for meals by name.

Input:

{
  "name": "pasta"
}

Output:

Found 30 meals for "pasta". Top 5:

- **Fettuccine Alfredo** (ID: 52794)
  Image: https://www.themealdb.com/images/media/meals/...

- **Spaghetti Carbonara** (ID: 52800)
  Image: https://www.themealdb.com/images/media/meals/...

[... 3 more meals ...]

---

2. random_meal

Get a random meal for culinary inspiration.

Input:

{}

Output:

**Pad Thai**

**Category:** Seafood | **Area:** Thai

**Ingredients:**
- 2 tablespoons Tamarind Paste
- 2 tablespoons Fish Sauce
- 1 tablespoon Oyster Sauce
- 1 tablespoon Lime Juice
- 2 Cloves Garlic
- 2 Chicken Breasts
- 8 oz Rice Noodles
- 2 Eggs
- 100g Beansprouts
- 50g Peanuts
- ... and 5 more

**Instructions:**
Heat oil in a wok over high heat. Add minced garlic and stir-fry until fragrant. Add chicken and cook until done. Add noodles and toss well. Pour sauce mixture and stir...

**Image:** https://www.themealdb.com/images/media/meals/...

---

3. meals_by_category

Browse meals by category.

Input:

{
  "category": "Seafood"
}

Output:

Found 23 meals in "Seafood" category. Showing top 10:

- **Baked Salmon** (ID: 52959)
  Image: https://www.themealdb.com/images/media/meals/...

- **Fish and Chips** (ID: 52802)
  Image: https://www.themealdb.com/images/media/meals/...

[... 8 more meals ...]

Popular Categories:

• Seafood
• Vegetarian
• Pasta
• Meat
• Breakfast
• Dessert
• Vegan
• Starter

---

4. meals_by_ingredient

Find meals that use a specific ingredient.

Input:

{
  "ingredient": "chicken"
}

Output:

Found 89 meals with "chicken" ingredient. Showing top 10:

- **Chicken Fajita Supreme** (ID: 52847)
  Image: https://www.themealdb.com/images/media/meals/...

- **Chicken Biryani** (ID: 52957)
  Image: https://www.themealdb.com/images/media/meals/...

[... 8 more meals ...]

---

5. get_meal_details

Get complete recipe details for a meal by ID.

Input:

{
  "meal_id": "52959"
}

Output:

# Baked Salmon

**Category:** Seafood
**Cuisine:** Canadian
**ID:** 52959

## Ingredients (7)

- 1 tbsp Butter
- 1/2 cup White Wine
- 2 tbsp Lemon Juice
- 1 tsp Dill
- 1 Salmon Fillet
- Salt and Pepper to taste
- Fresh Lemon

## Instructions

Preheat oven to 375°F (190°C). Place salmon fillet on a baking sheet. Melt butter and mix with white wine, lemon juice, and dill. Pour over salmon. Season with salt and pepper. Bake for 15-20 minutes until cooked through. Serve immediately with fresh lemon wedges.

## Video Recipe
[Watch on YouTube](https://www.youtube.com/watch?v=...)

## Image
![Baked Salmon](https://www.themealdb.com/images/media/meals/...)

---

Features

✅ Production-Ready

• TypeScript with strict mode
• Comprehensive input validation
• Proper error handling
• 404 detection and rate limit handling

✅ Minimal Dependencies

• @modelcontextprotocol/sdk - MCP protocol implementation
• node-fetch - HTTP client (compatible with Node.js 18+)
• No other runtime dependencies

✅ Well-Structured

• Clean separation of concerns (API, tools, validation)
• Type-safe responses
• Modular handlers for each tool

✅ Free & Open

• No authentication required
• Powered by TheMealDB free API
• No rate limiting in normal usage

Project Structure

mealsmcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── api/
│   │   └── mealdb-client.ts  # TheMealDB API client
│   ├── tools/
│   │   ├── search-handler.ts    # Search & random meal handlers
│   │   ├── filter-handler.ts    # Category & ingredient filters
│   │   └── details-handler.ts   # Meal details handler
│   └── utils/
│       └── validation.ts      # Input validation & sanitization
├── dist/                     # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Development

# Type check
npm run typecheck

# Development (with ts-node)
npm run dev

# Test all tools with sample requests
npm test

# Build
npm run build

# Start compiled server
npm start

Error Handling

The server handles common error scenarios gracefully:

• Invalid inputs - Sanitizes and validates before API calls
• Empty results - Returns friendly "no meals found" messages
• HTTP errors - Catches 404s, rate limits, and server errors
• Network failures - Provides meaningful error messages

Requirements

• Node.js 18.0.0 or later
• npm or yarn

License

MIT

API Attribution

Built with TheMealDB - A free, crowd-sourced database of meals from around the world.