USDA Nutrition Database MCP Server

A comprehensive Model Context Protocol (MCP) server that provides intelligent access to the USDA nutrition database through AI assistants like Claude Desktop. Transform complex nutrition data into conversational queries and get authoritative answers about food composition, nutritional content, and dietary analysis.

<N What This Provides

• = Smart Food Search - Find foods by keywords across 7,146+ items
• =Ê Complete Nutrition Profiles - Get detailed nutrition data for any food
• –� Food Comparisons - Compare nutritional content between foods
• =ª Nutrient-Focused Discovery - Find foods highest in specific nutrients
• =Â� Category Browsing - Explore foods by category (24 major groups)
• >ì Scientific Data Access - Direct access to USDA's authoritative nutrition database

=€ Quick Start

Prerequisites

• Python 3.13+
• PostgreSQL with USDA nutrition database loaded
• Claude Desktop (recommended) or MCP-compatible client

Installation

1. Clone the repository:

   git clone https://github.com/your-username/usda-mcp-server.git
   cd usda-mcp-server

2. Install dependencies:

   # Using pip
   pip install -r requirements.txt
   
   # Using uv (recommended)
   uv sync

3. Configure database connection:

   Edit the database configuration in main.py if needed:

   db_config = {
       "host": "localhost",
       "port": 5432,
       "database": "usda",
       "user": "postgres",
       "password": "postgres"
   }

4. Configure Claude Desktop:

   Add to your claude_desktop_config.json:

   {
     "mcpServers": {
       "usda-postgres": {
         "command": "python",
         "args": ["/absolute/path/to/main.py"]
       }
     }
   }

5. Start using:

   Restart Claude Desktop and ask questions like:

   • "Find foods high in protein"
   • "Compare the nutrition of chicken and salmon"
   • "What are the different types of apples in the database?"

=à� Available Tools

The MCP server provides 10 specialized tools:

Core Database Tools

Tool	Description
execute_query	Execute custom SQL queries on the database
list_tables	List all available database tables
describe_table	Get schema information for any table
get_table_sample	View sample data from any table

Nutrition-Specific Tools

Tool	Description
search_foods	Search foods by keyword in names/descriptions
get_nutrition_profile	Get complete nutrition data for a specific food
get_foods_by_category	Browse foods within specific categories
get_food_categories	List all food categories with counts
compare_foods_nutrition	Compare nutrition between multiple foods
find_foods_high_in_nutrient	Find foods with highest amounts of specific nutrients

=¬ Claude Desktop Integration Examples

Finding High-Protein Foods

Nutrition Comparison Between Foods

Interactive Food Search

>ê Testing

Method 1: Automated Test Suite

python test_mcp_server.py

This comprehensive test script validates:

• Database connectivity
• All tool functionality
• Performance benchmarking
• Interactive demos

Method 2: MCP Inspector (Web UI)

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Launch web interface
mcp-inspector python main.py

Open http://localhost:5173 to browse tools and test interactively.

Method 3: Command Line Testing

# Install MCP CLI
npm install -g @modelcontextprotocol/cli

# List available tools
mcp list-tools python main.py

# Test a specific tool
mcp call-tool python main.py search_foods '{"keyword": "apple", "limit": 5}'

Method 4: Direct Python Testing

import asyncio
from main import mcp

async def test():
    result = await mcp.call_tool("search_foods", {"keyword": "chicken"})
    print(result)

asyncio.run(test())

=Ê Database Overview

The USDA database contains:

Table	Rows	Description
food_des	7,146	Food descriptions and metadata
nut_data	253,825	Nutrition values for each food/nutrient
nutr_def	136	Nutrient definitions and units
fd_group	24	Food category classifications
data_src	366	Scientific references and sources
Others	5,100+	Supporting data (weights, footnotes, etc.)

Total: 368,416+ records of authoritative nutrition data

Key Statistics

• 7,146 foods across 24 major categories
• 136 different nutrients tracked (vitamins, minerals, macronutrients)
• Most tracked nutrient: Energy (6,746 foods have calorie data)
• Largest category: Vegetables and Vegetable Products (788 foods)
• Data sources: 366 scientific studies and references

<� Architecture

Technology Stack

• Python 3.13+ with asyncio for high-performance async operations
• FastMCP for clean, decorator-based tool definitions
• asyncpg for high-performance PostgreSQL connectivity
• Connection pooling for efficient database resource management

Key Components

# MCP Server with tool decorators
mcp = FastMCP("usda-postgres")

@mcp.tool()
async def search_foods(keyword: str, limit: int = 20) -> str:
    """Search for foods by keyword"""
    # Implementation with optimized queries

Performance Features

• Connection pooling for database efficiency
• Async operations for concurrent request handling
• Optimized SQL queries with proper indexing
• JSON responses with structured data formatting

=' Configuration

Database Connection

Update main.py database configuration as needed:

db_config = {
    "host": "localhost",        # Database host
    "port": 5432,              # PostgreSQL port  
    "database": "usda",        # Database name
    "user": "postgres",        # Database user
    "password": "postgres"     # Database password
}

Claude Desktop Setup

Location of config file by OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

=� Troubleshooting

Common Issues

"Database connection failed"

# Check if PostgreSQL is running
pg_ctl status

# Verify database exists
psql -h localhost -U postgres -l | grep usda

# Test connection
psql -h localhost -U postgres -d usda -c "SELECT COUNT(*) FROM food_des;"

"No module named 'mcp'"

# Install dependencies
pip install -r requirements.txt
# or
uv sync

"Tools not appearing in Claude Desktop"

1. Verify absolute path in config file
2. Restart Claude Desktop completely
3. Check server logs: python main.py 2>&1 | tee server.log

Performance Issues

# Check database indexes
psql -h localhost -U postgres -d usda -c "SELECT schemaname, tablename, indexname FROM pg_indexes WHERE schemaname = 'public';"

=È Performance Benchmarks

Based on testing with the included test suite:

• Average response time: ~70ms per query
• Concurrent requests: Handles 5+ simultaneous requests efficiently
• Database queries: Optimized with proper indexing and connection pooling
• Memory usage: Efficient with connection pooling and async operations

<¯ Use Cases

For Nutritionists & Dietitians

• Quick lookup of comprehensive nutrition data
• Compare foods for meal planning
• Find best sources of specific nutrients
• Generate evidence-based recommendations

For Researchers

• Access authoritative USDA nutrition data
• Analyze nutritional patterns across food categories
• Cross-reference multiple nutrients efficiently
• Export data for further analysis

For Health-Conscious Consumers

• Make informed food choices
• Find foods high in desired nutrients
• Compare nutritional value of alternatives
• Learn about food composition

For Food Industry

• Analyze competitive products
• Develop recipes targeting nutritional goals
• Ensure accurate nutritional labeling
• Research ingredient alternatives

=ã� Roadmap

Planned Features

• Recipe Analysis - Calculate nutrition for complete recipes
• Dietary Matching - Find foods meeting specific dietary requirements
• Portion Size Calculations - Convert between different serving sizes
• Trend Analysis - Nutritional patterns across food categories
• Export Functionality - CSV/Excel export of query results

Technical Improvements

• Caching Layer for frequently accessed data
• Full-text Search for more sophisticated food discovery
• GraphQL Interface for flexible data querying
• Real-time Updates as USDA releases new data
• Docker Support for easier deployment

>� Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Install dependencies: uv sync
4. Run tests: python test_mcp_server.py
5. Make your changes
6. Run tests again to ensure everything works
7. Submit a pull request

=Ý License

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

=O Acknowledgments

• USDA for maintaining the comprehensive nutrition database
• Anthropic for developing the Model Context Protocol
• PostgreSQL team for the robust database system
• FastMCP developers for the excellent Python framework

=Ú Additional Resources

• USDA Food Data Central - Official USDA nutrition database
• Model Context Protocol Documentation - MCP specification and guides
• Claude Desktop - Download Claude Desktop application
• PostgreSQL Documentation - Database setup and configuration

=Þ Support

If you encounter any issues or have questions:

1. Check the Troubleshooting section
2. Run the test suite: python test_mcp_server.py
3. Check existing Issues
4. Create a new issue with detailed information

---

Built with d� for the nutrition and AI communities

Making authoritative nutrition data accessible through intelligent AI conversations