usda-mcp-server

v0.2.2 pre-1.0

Search foods, compare nutrients, and look up the full USDA FoodData Central database via MCP. STDIO or Streamable HTTP.

usda.caseyjhand.com/mcp
claude mcp add --transport http usda-mcp-server https://usda.caseyjhand.com/mcp
codex mcp add usda-mcp-server --url https://usda.caseyjhand.com/mcp
{
  "mcpServers": {
    "usda-mcp-server": {
      "url": "https://usda.caseyjhand.com/mcp"
    }
  }
}
gemini mcp add --transport http usda-mcp-server https://usda.caseyjhand.com/mcp
{
  "mcpServers": {
    "usda-mcp-server": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://usda.caseyjhand.com/mcp"
      ]
    }
  }
}
{
  "mcpServers": {
    "usda-mcp-server": {
      "type": "http",
      "url": "https://usda.caseyjhand.com/mcp"
    }
  }
}
curl -X POST https://usda.caseyjhand.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Tools

5

usda_list_nutrients

Look up the FDC nutrient reference table — all tracked nutrients with their numeric IDs, names, SR reference numbers, units, and categories. Use to resolve a nutrient name (e.g. "vitamin C") to its FDC ID (1162) before passing it to the nutrients[] filter on other tools. Filter by category (macronutrients, vitamins, minerals, lipids, amino_acids, or other) to narrow results. The data is static — call once and reuse the IDs.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "usda_list_nutrients",
    "arguments": {}
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "category": {
      "description": "Filter to a nutrient category. Omit to return all ~150 tracked nutrients. Options: macronutrients, vitamins, minerals, lipids, amino_acids, other.",
      "type": "string",
      "enum": [
        "macronutrients",
        "vitamins",
        "minerals",
        "lipids",
        "amino_acids",
        "other"
      ]
    }
  },
  "additionalProperties": false
}
view source ↗

usda_search_foods

open-world

Search USDA FoodData Central foods by keyword. Returns matching foods with FDC IDs and available preview nutrients: protein (1003), fat (1004), carbohydrate (1005), fiber (1079), and energy (1008, 1062, 2047, 2048), preserving distinct energy estimates. Missing nutrients are omitted. Use the returned fdcId with usda_get_food for other nutrients or the full profile, or usda_compare_foods for side-by-side comparisons. When dataType is omitted, defaults to SR Legacy (common whole foods with complete profiles), to Branded when brandOwner is set (only Branded records carry one), or to Branded and Survey (FNDDS) when the query is 8–14 digits alone (a UPC/GTIN barcode or an FNDDS food code). A 12–14-digit barcode with a valid check digit also matches the other digit forms FDC stores it in. Set dataType to ["Branded"] for packaged products. Pass brandOwner (e.g. "General Mills") to narrow branded results.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "usda_search_foods",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Search terms — food name, ingredient, or UPC/GTIN code. Examples: \"chicken breast raw\", \"banana\", \"02114029705\". A food matching any one unqualified word counts, so a multi-word query also returns foods holding only some of its words; set requireAllWords, or prefix each word with +, to require them all. A query of 8–14 digits alone matches a Branded UPC/GTIN code or an 8-digit Survey (FNDDS) food code. A 12-, 13-, or 14-digit code with a valid GTIN check digit (a printed UPC-A or EAN-13) also matches the other digit forms FDC stores that GTIN in: leading zeros added or dropped down to 12 digits, and the 12-digit form without its check digit. Any other code matches only as FDC stores it, leading zeros included. FDC reads Lucene syntax: \"quoted phrases\", +required and -excluded terms, AND/OR/NOT, wildcards (chick*), fuzzy matches (beeef~), boosts (beef^5), grouping parentheses, field:value, regex terms (/chick.*/), and ranges ([a TO c], {a TO c}). Any other slash, bracket, or brace (1/8, w/o, beef [raw]), any unpaired parenthesis, and every double quote when the query holds an odd number of them are sent as literal characters."
    },
    "requireAllWords": {
      "default": false,
      "description": "Match only foods containing every query word (FDC requireAllWords). Default false: a food matching any one word counts. Explicit OR and \"quoted phrases\" keep their meaning.",
      "type": "boolean"
    },
    "dataType": {
      "description": "FDC data sources to search. Omitting this defaults to [\"SR Legacy\"] (common whole foods, complete nutrient profiles), to [\"Branded\"] when brandOwner is set, or to [\"Branded\", \"Survey (FNDDS)\"] when the query is 8–14 digits alone (a UPC/GTIN barcode or an FNDDS food code). Include \"Branded\" for packaged products. Multiple values allowed.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "SR Legacy",
          "Foundation",
          "Survey (FNDDS)",
          "Branded"
        ]
      }
    },
    "brandOwner": {
      "description": "Filter branded results by brand owner name (e.g. \"General Mills\", \"Kraft\"). Matched as one phrase, ignoring case and punctuation: \"Kellogg Company\" matches owners holding those words in that order. A value containing * or ? is sent as wildcard terms instead, each word matched on its own (e.g. \"Kellog*\"). For other operators, use field syntax in query (e.g. \"+cereal +brandOwner:Kellog*\"). Only Branded records carry one, so setting this defaults dataType to [\"Branded\"] unless dataType is given explicitly.",
      "type": "string"
    },
    "foodCategory": {
      "description": "Filter by USDA food category (e.g. \"Poultry Products\", \"Vegetables and Vegetable Products\"). Matched as one phrase, ignoring case and punctuation. A value containing * or ? is sent as wildcard terms instead, each word matched on its own (e.g. \"Poult*\"); a whole word followed by * can match nothing (\"Poultry*\" does), so shorten it. For other operators, use field syntax in query (e.g. chicken -foodCategory:\"Fast Foods\" excludes a category).",
      "type": "string"
    },
    "pageSize": {
      "default": 10,
      "description": "Number of results per page. Default 10, maximum 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "pageNumber": {
      "default": 1,
      "description": "Page number (1-based). Use with totalPages to paginate. FDC serves only the first 100,000 results of a search, so a page whose pageSize × pageNumber exceeds 100,000 fails with result_window_exceeded, naming the last reachable page, unless it is also past the last page. A page past the last returns empty foods with a notice naming the last reachable page when the query has matches.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query",
    "requireAllWords",
    "pageSize",
    "pageNumber"
  ],
  "additionalProperties": false
}
view source ↗

usda_get_food

Get the full nutrient profile for one food by FDC ID. Returns all available nutrients (or a filtered subset via the nutrients[] param) with optional per-portion scaling. Use usda_search_foods to discover FDC IDs. Values are per 100 g (basisUnit "g"), except Branded foods FDC reports per 100 ml (basisUnit "ml") or per 100 of a label unit that fixes neither (basisUnit absent, basis unverified). Provide unit, optionally with quantity, to scale all nutrient values from that basis to that amount (e.g. quantity=200, unit="g" → per-200g values); a mass unit is applied to an ml or label-unit basis without conversion, and a notice says so. quantity defaults to 100 for g, oz, lb, and kg and to 1 for serving. Serving uses the valid portion FDC displays first (lowest sequenceNumber), or a positive finite Branded label size in g/GRM/GM (case-insensitive) when no portion exists; quantity multiplies that weight. A label in any other unit sets the basis rather than a serving weight, so it requires an explicit mass-unit request. quantity without unit is rejected. Narrow nutrients[] to specific IDs to reduce response size for focused queries.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "usda_get_food",
    "arguments": {
      "fdcId": "<fdcId>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "fdcId": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991,
      "description": "FDC ID of the food. Use usda_search_foods to discover IDs."
    },
    "nutrients": {
      "description": "Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008] for protein, fat, carbs, energy). Use usda_list_nutrients to look up IDs. Omit to return all available nutrients. Requested IDs the food does not report are listed in missingNutrients.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    },
    "quantity": {
      "description": "Amount of food, in unit, to scale nutrient values to. Must be positive. Requires unit. Defaults to 100 when unit is g, oz, lb, or kg, and to 1 when unit is \"serving\". Omit both quantity and unit for the per-100 values FDC reports (per 100 g, or per 100 ml when basisUnit is \"ml\").",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "unit": {
      "description": "Unit for quantity. \"serving\" uses the weight of the valid portion FDC displays first (lowest sequenceNumber), or a Branded label size in g/GRM/GM (case-insensitive) when no portion exists, multiplied by quantity. Required when quantity is provided. Given alone, scales to 100 g, oz, lb, or kg, or to 1 serving.",
      "type": "string",
      "enum": [
        "g",
        "oz",
        "lb",
        "kg",
        "serving"
      ]
    }
  },
  "required": [
    "fdcId"
  ],
  "additionalProperties": false
}
view source ↗

usda_get_foods

Fetch nutrient profiles for several foods at once. More efficient than calling usda_get_food N times when you already have multiple FDC IDs. Accepts up to 500 IDs: repeats are dropped, the first 20 distinct IDs are fetched, and the rest are returned in deferredIds for a follow-up call. IDs FDC does not return before the call's deadline (slow Foundation records, most often) or keeps failing on also come back in deferredIds, ahead of those, named in a notice. Values are per 100 of each food's basisUnit, with no portion scaling: per 100 g (basisUnit "g"), except Branded foods FDC reports per 100 ml (basisUnit "ml") or per 100 of a label unit that fixes neither (basisUnit absent, basis unverified). Use the nutrients[] filter to limit response size — strongly recommended for batch calls; requested IDs a food does not report are listed in its missingNutrients. For side-by-side comparison with a formatted table, use usda_compare_foods instead. Failed IDs (not found or no data) are reported in the failed[] array rather than aborting the entire batch.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "usda_get_foods",
    "arguments": {
      "fdcIds": "<fdcIds>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "fdcIds": {
      "minItems": 2,
      "maxItems": 500,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      },
      "description": "FDC IDs to fetch — 2 to 500 entries (a server configured with strict limits rejects more than 20). Repeats are dropped; the first 20 distinct IDs are fetched and the rest are returned in deferredIds. Use usda_search_foods to discover IDs."
    },
    "nutrients": {
      "description": "Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008]). Strongly recommended — full profiles can be large. Use usda_list_nutrients to look up IDs. Requested IDs a food does not report are listed in its missingNutrients.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    }
  },
  "required": [
    "fdcIds"
  ],
  "additionalProperties": false
}
view source ↗

usda_compare_foods

Compare nutrients side-by-side for 2–5 foods. Returns a structured table — one row per nutrient, one column per food — formatted as markdown. Best for "spinach vs kale iron" or "which has more protein?" questions. Omit nutrients[] to use the 12 most common defaults (energy, protein, fat, saturated fat, carbs, fiber, sugars, sodium, potassium, calcium, iron, vitamin C); a food that lacks the default energy (1008) or total sugars (2000) value has that cell filled from its equivalent nutrient — energy from 2048, then 2047; sugars from 1063 — and each fill is listed in substitutions. Provide nutrients[] with specific FDC IDs to compare different nutrients; an explicit list is compared as given, without fills. All values are scaled to the same basis, quantity in unit: default 100 g, so unit="oz" alone compares per 100 oz and quantity alone is grams. A Branded food FDC reports per 100 ml (basisUnit "ml") or per 100 of a label unit that fixes neither (basisUnit absent) is compared on that basis without conversion, and a notice names it. If one or more FDC IDs are not found, the comparison proceeds with the valid foods — only throws too_few_foods when fewer than 2 IDs return data. IDs FDC does not return before the call's deadline (slow Foundation records, most often) or keeps failing on are left out, listed in deferredIds, and named in a notice; when that leaves fewer than 2 foods, the call fails with retry_deadline_exceeded instead, or with too_few_foods when even answers for the deferred IDs could not make 2 foods.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "usda_compare_foods",
    "arguments": {
      "fdcIds": "<fdcIds>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "fdcIds": {
      "minItems": 2,
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      },
      "description": "FDC IDs to compare — 2 to 5 foods. Use usda_search_foods to discover IDs."
    },
    "nutrients": {
      "description": "Nutrient IDs to include in the comparison. Defaults to the 12 most common: energy (1008), protein (1003), total fat (1004), saturated fat (1258), carbohydrate (1005), fiber (1079), total sugars (2000), sodium (1093), potassium (1092), calcium (1087), iron (1089), vitamin C (1162). Under the defaults, a food missing energy or total sugars has that cell filled from its equivalent nutrient (listed in substitutions); IDs given here are compared as given. Use usda_list_nutrients to look up other IDs.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    },
    "quantity": {
      "default": 100,
      "description": "Amount of food, in unit, that every value is scaled to. Must be positive. Default 100.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "unit": {
      "default": "g",
      "description": "Unit for quantity. Default \"g\". Does not support \"serving\" (each food's portion weight differs, so a serving basis would not compare equal amounts).",
      "type": "string",
      "enum": [
        "g",
        "oz",
        "lb",
        "kg"
      ]
    }
  },
  "required": [
    "fdcIds",
    "quantity",
    "unit"
  ],
  "additionalProperties": false
}
view source ↗

Resources

2

Full nutrient profile for a specific food by FDC ID. Returns all available nutrients per 100 of basisUnit: per 100 g, or per 100 ml for a Branded food labeled in ml; absent basisUnit means a label unit that fixes neither. Equivalent to usda_get_food without portion scaling. Use usda_search_foods to discover FDC IDs.

uri usda://food/{fdcId} mime application/json

Access the complete FDC nutrient reference — all ~150 tracked nutrients with their numeric IDs, names, SR reference numbers, units, and categories. Use to resolve nutrient names to FDC IDs for the nutrients[] filter on usda_get_food, usda_get_foods, usda_compare_foods, and usda_list_nutrients.

uri usda://nutrients mime application/json

Extensions

1

io.modelcontextprotocol/skills

{
  "directoryRead": true
}