Getting Started
The Ziva MCP server integrates nutrition tracking into any MCP-compatible AI assistant. It operates in stateless mode using OAuth tokens for authentication.
Connection
Key Features
- ✓ Stateless design: No persistent session handshakes required
- ✓ Per-request OAuth: Authentication via OAuth tokens
- ✓ 11 tools: Food search, meal logging, saved items, insights
- ✓ Universal: Works with ChatGPT, Claude, Gemini, and any MCP client
Authentication
All tools require OAuth 2.0 authentication. The authentication flow is managed by your AI client (ChatGPT, Claude, etc.). Once authorized, the OAuth token is automatically included with every request.
Note: Users authorize Ziva through their AI client's interface. All data is scoped to the authenticated user.
Token Claims
Food Search
search_usda_foods
Search the USDA FoodData Central database for foods. Supports multiple queries and returns available portions with macro data per 100g.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| queries | string[] | required | List of foods (1-20) |
| limit_per_query | integer | optional | Default: 5, max: 20 |
| data_source | enum | optional | 'survey' | 'branded' | 'both' |
Example
{
"queries": ["chicken breast", "brown rice"],
"limit_per_query": 5,
"data_source": "both"
}get_food_details
Get detailed nutritional data for specific USDA foods by FoodData Central ID.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| fdc_ids | integer[] | required | Food IDs (1-50) |
Meal Logging
log_meal
Create or update meal log entries. Meals can mix USDA foods and quick-log items.
Workflow: Search foods → Select best match → Verify portions → Log meal
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| foodItems | object[] | optional | USDA or quick-log items |
| description | string | optional | Meal name |
| mealDate | string | optional | YYYY-MM-DD. Default: today |
USDA Food Item
{
"type": "usda",
"fdcId": 171705,
"portionId": 1,
"quantity": 2
}Quick-Log Food Item
{
"type": "quick",
"description": "House sauce",
"calories": 50,
"protein": 1,
"fat": 4,
"carbs": 3
}get_meals_for_date
Retrieve all meals for a date or date range.
search_meal_history
Full-text search through meal history by description.
delete_meal
Permanently delete one or more meal entries.
Saved Items
Users can save meals and recipes for quick re-logging. When logging from a saved item, call get_saved_item first to get full ingredient details.
save_item
Create or update a saved meal/recipe.
get_saved_item
Get full details and ingredients of a saved item.
search_saved_items
Search or list all saved meals and recipes.
delete_saved_item
Permanently delete saved meals or recipes.
Insights
get_insights
Get aggregated nutrition data for daily, weekly, or monthly periods. Returns macro totals and daily averages for trend analysis.
Error Handling
401 Unauthorized
Token expired or invalid. User needs to re-authenticate with Ziva in their AI client.
No Search Results
Try simplifying the query by removing cooking methods or preparation styles:
"grilled chicken thigh" → "chicken thigh"
"melted sharp cheddar" → "cheddar cheese"
Portion Seems Wrong
Verify gram weight matches the description. If not, try a different search result or use quick-log with estimated macros.
Best Practices
- • Use standard USDA naming conventions
- • Always verify portions before logging
- • Use quick-log only as a fallback
- • Call get_saved_item before logging from a saved meal