Food MCP Server + Agent

A two-stage AI project: an MCP server exposing cooking/recipe tools backed by the Spoonacular API, and a Gemini-powered agent built on top of it that answers natural-language cooking questions by calling those tools.

Why MCP here

Rather than gluing an LLM directly to a food API with custom prompt-stuffed context, MCP exposes each capability as a typed, documented tool that any compliant client (Claude Desktop, a custom agent, etc.) can discover and call on its own. The model decides when to call search_recipes_by_ingredients vs. get_ingredient_substitutes based on the tool descriptions — it isn't hardcoded into a single prompt.

Tools

Tool	Purpose
search_recipes	Natural-language recipe search with diet/cuisine/time filters
search_recipes_by_ingredients	"What can I cook with what I have"
get_recipe_details	Full recipe: ingredients, steps, image, source
get_recipe_nutrition	Calorie and macro/nutrient breakdown for a recipe
get_ingredient_substitutes	Suggested swaps for an ingredient you don't have

These five were chosen deliberately (over exposing Spoonacular's full endpoint list) so they compose well for an agent: e.g. "find a vegetarian recipe from these ingredients, show me the nutrition, and suggest a substitute for the one thing I'm missing" chains three of these tools naturally.

Setup

pip install -r requirements.txt
cp .env.example .env
# edit .env and add your free Spoonacular API key

Run the server on its own

python server.py

This starts the server over stdio, the standard transport for local MCP clients. You don't need to do this before running the agent below — it's only useful for testing the server in isolation.

Test the server with the MCP Inspector

Use the MCP Inspector to call tools directly and see raw input/output before wiring this into an agent:

npx @modelcontextprotocol/inspector python server.py

Use it with Claude Desktop

Add to your Claude Desktop MCP config:

{
  "mcpServers": {
    "food": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": { "SPOONACULAR_API_KEY": "your_key_here" }
    }
  }
}

The agent (stage 2)

agent.py is a command-line agent built on top of this server. It uses Google Gemini's function-calling API to turn a plain-language question into one or more tool calls, chaining them together when needed — e.g. "find me a quick vegetarian dinner and check if it's healthy" triggers search_recipes, then get_recipe_nutrition on the result, with the agent deciding that sequence on its own from the tool descriptions.

It's written directly against the raw Gemini API and the raw MCP client (rather than an agent framework like LangChain), so the tool-calling loop is fully visible in the code.

Agent setup

# add to your .env, alongside SPOONACULAR_API_KEY
GOOGLE_API_KEY=your_key_here   # free at https://aistudio.google.com/apikey

Run the agent

python agent.py

You don't need to run server.py separately — the agent launches it automatically as a subprocess and talks to it over stdio.

Example session

You: find me a quick vegetarian dinner and check if it's healthy

[calling tool: search_recipes({"query": "vegetarian dinner", "diet": "vegetarian", "max_ready_minutes": 30})]

[calling tool: get_recipe_nutrition({"recipe_id": 123456})]

Gemini: I found a vegetarian stir-fry ready in 25 minutes — it's about
480 calories with a good protein-to-carb balance, so a reasonably
healthy pick for a quick dinner.

Roadmap

Stages 1 (MCP server) and 2 (agent) are both built. Possible future additions: search_recipes_by_diet, get_similar_recipes, convert_ingredient_amount, and a web/chat UI in place of the command-line interface.

Notes

• Free-tier Spoonacular quota is limited per day; the server surfaces a clear error if you hit it rather than failing silently.
• API keys are read from environment / .env, never hardcoded.
• The agent originally targeted Claude's API, then was moved to Gemini's free tier to keep this project cost-free. The MCP server needed zero changes for that swap — only the agent's model-calling logic and tool schema conversion did, since MCP standardizes the tool layer but not the underlying model API.