FatSecret MCP Server

A Model Context Protocol (MCP) server that provides access to the FatSecret nutrition database API with full 3-Legged OAuth authentication support.

Features

• Complete OAuth 1.0a Implementation: Full 3-legged OAuth flow for user authentication
• Food Database Access: Search and retrieve detailed nutrition information
• Recipe Database: Search for recipes and get detailed cooking instructions
• User Data Management: Access user food diaries and add food entries
• Secure Credential Storage: Encrypted storage of API credentials and tokens

Getting Started

Prerequisites

• Node.js (v14 or higher)
• npm or yarn
• A FatSecret developer account

Installation

# Clone the repository
git clone https://github.com/your-username/fatsecret-mcp.git
cd fatsecret-mcp

# Install dependencies
npm install

# Build the TypeScript
npm run build

Setup

1. Get FatSecret API Credentials

1. Visit the FatSecret Platform
2. Create a developer account and register your application
3. Note down your Client ID and Client Secret

2. Configure the MCP Server

The server needs to be configured in your MCP client (like Claude Desktop). Add this to your MCP configuration:

{
  "mcpServers": {
    "fatsecret": {
      "command": "node",
      "args": ["path/to/fatsecret-mcp-server/dist/index.js"]
    }
  }
}

3. Authentication Process

Option 1: Using the OAuth Console Utility (Recommended)

The easiest way to authenticate is using the included OAuth console utility:

# Make sure you've built the project first
npm run build

# Run the OAuth console utility
node dist/cli.js

This interactive utility will:

1. Ask for your Client ID and Client Secret
2. Save them securely in ~/.fatsecret-mcp-config.json
3. Guide you through the OAuth flow:
   • Opens your browser to the FatSecret authorization page
   • Prompts you to paste the verifier code after authorization
   • Saves the access tokens for future use

Option 2: Manual Authentication via MCP Tools

If you prefer to authenticate through the MCP interface (e.g., in Claude):

1. Set your API credentials:

   Use tool: set_credentials
   Parameters:
   - clientId: "your_client_id_here"
   - clientSecret: "your_client_secret_here"

2. Start the OAuth flow:

   Use tool: start_oauth_flow
   Parameters:
   - callbackUrl: "oob" (for out-of-band authentication)

3. Visit the authorization URL provided in the response:

   • Log in to your FatSecret account (or create one)
   • Click "Allow" to authorize the application
   • Copy the verifier code shown on the page

4. Complete the OAuth flow:

   Use tool: complete_oauth_flow
   Parameters:
   - requestToken: [from step 2 response]
   - requestTokenSecret: [from step 2 response]
   - verifier: [the code you copied from the authorization page]

Option 3: Using Environment Variables

You can also provide credentials via environment variables:

# Create a .env file in the project root
CLIENT_ID=your_client_id_here
CLIENT_SECRET=your_client_secret_here

# The server will automatically load these on startup

Note: You'll still need to complete the OAuth flow for user-specific operations.

Usage

1. Set API Credentials

First, set your FatSecret API credentials:

Use the set_credentials tool with your Client ID and Client Secret

2. Authenticate a User (3-Legged OAuth)

For user-specific operations, you need to complete the OAuth flow:

1. Use start_oauth_flow tool (with callback URL or "oob" for out-of-band)
2. Visit the provided authorization URL
3. Authorize the application and get the verifier code
4. Use complete_oauth_flow tool with the request token, secret, and verifier

3. Use the API

Once authenticated, you can use all available tools:

Food Search and Information

• search_foods: Search for foods in the database
• get_food: Get detailed nutrition information for a specific food

Recipe Search and Information

• search_recipes: Search for recipes
• get_recipe: Get detailed recipe information including ingredients and instructions

User Data (Requires Authentication)

• get_user_profile: Get the authenticated user's profile
• get_user_food_entries: Get food diary entries for a specific date
• add_food_entry: Add a food entry to the user's diary

Utility

• check_auth_status: Check current authentication status

Available Tools

Authentication Tools

set_credentials

Set your FatSecret API credentials.

Parameters:

• clientId (string, required): Your FatSecret Client ID
• clientSecret (string, required): Your FatSecret Client Secret

start_oauth_flow

Start the 3-legged OAuth flow.

Parameters:

• callbackUrl (string, optional): OAuth callback URL (default: "oob")

complete_oauth_flow

Complete the OAuth flow with authorization.

Parameters:

• requestToken (string, required): Request token from start_oauth_flow
• requestTokenSecret (string, required): Request token secret from start_oauth_flow
• verifier (string, required): OAuth verifier from authorization

check_auth_status

Check current authentication status.

Food Database Tools

search_foods

Search for foods in the FatSecret database.

Parameters:

• searchExpression (string, required): Search term
• pageNumber (number, optional): Page number (default: 0)
• maxResults (number, optional): Max results per page (default: 20)

get_food

Get detailed information about a specific food.

Parameters:

• foodId (string, required): FatSecret food ID

Recipe Database Tools

search_recipes

Search for recipes in the FatSecret database.

Parameters:

• searchExpression (string, required): Search term
• pageNumber (number, optional): Page number (default: 0)
• maxResults (number, optional): Max results per page (default: 20)

get_recipe

Get detailed information about a specific recipe.

Parameters:

• recipeId (string, required): FatSecret recipe ID

User Data Tools (Requires Authentication)

get_user_profile

Get the authenticated user's profile information.

get_user_food_entries

Get user's food diary entries for a specific date.

Parameters:

• date (string, optional): Date in YYYY-MM-DD format (default: today)

add_food_entry

Add a food entry to the user's diary.

Parameters:

• foodId (string, required): FatSecret food ID
• servingId (string, required): Serving ID for the food
• quantity (number, required): Quantity of the serving
• mealType (string, required): Meal type (breakfast, lunch, dinner, snack)
• date (string, optional): Date in YYYY-MM-DD format (default: today)

Example Workflow

1. Setup Credentials:

   Tool: set_credentials
   - clientId: "your_client_id"
   - clientSecret: "your_client_secret"

2. Search for Foods:

   Tool: search_foods
   - searchExpression: "chicken breast"

3. Get Food Details:

   Tool: get_food
   - foodId: "12345"

4. Authenticate User (if needed):

   Tool: start_oauth_flow
   - callbackUrl: "oob"
   
   # Follow the authorization URL, then:
   
   Tool: complete_oauth_flow
   - requestToken: "from_start_oauth_flow"
   - requestTokenSecret: "from_start_oauth_flow"
   - verifier: "from_authorization_page"

5. Add Food to Diary:

   Tool: add_food_entry
   - foodId: "12345"
   - servingId: "67890"
   - quantity: 1
   - mealType: "lunch"

Configuration Storage

The server stores configuration (credentials and tokens) in ~/.fatsecret-mcp-config.json. This file contains:

• API credentials (Client ID and Secret)
• OAuth access tokens (when authenticated)
• User ID (when authenticated)

Security Notes

• Credentials are stored locally in your home directory
• OAuth tokens are securely managed using proper HMAC-SHA1 signing
• All API communications use HTTPS
• The server implements proper OAuth 1.0a security measures

API Reference

This server implements the FatSecret Platform API. For detailed API documentation, visit:

• FatSecret Platform API Documentation
• OAuth 1.0a Specification

Error Handling

The server provides detailed error messages for common issues:

• Missing or invalid credentials
• OAuth flow errors
• API rate limiting
• Network connectivity issues
• Invalid parameters

Testing

Testing from the Command Line

The project includes several test utilities:

1. Interactive Test Tool

# Run the interactive test menu
node test-interactive.js

This provides a menu-driven interface to test all MCP tools.

2. Date Conversion Test

# Test the date conversion logic
node test-date-conversion.js

Verifies that dates are correctly converted to FatSecret's "days since epoch" format.

3. Direct JSON-RPC Testing

# Send test messages via pipe
node test-mcp.js | node dist/index.js

Testing in Claude Desktop

1. Restart Claude Desktop after configuring the MCP server
2. Look for "fatsecret" in the available tools
3. Start by using check_auth_status to verify the connection

Troubleshooting

Common Issues

"Invalid integer value: date"

• The FatSecret API expects dates as days since epoch (1970-01-01)
• The server automatically converts YYYY-MM-DD format dates
• If you get this error, ensure you're using the latest version

OAuth Authentication Fails

• Verify your Client ID and Client Secret are correct
• Ensure you're using the correct URLs (authentication.fatsecret.com for OAuth)
• Check that you're copying the entire verifier code from the authorization page

Server Not Found in Claude

• Ensure the path in your MCP configuration is absolute, not relative
• Verify the server was built successfully (npm run build)
• Check Claude's logs for any error messages

"User authentication required"

• Complete the OAuth flow using either the CLI utility or MCP tools
• Check authentication status with check_auth_status tool
• Tokens are saved in ~/.fatsecret-mcp-config.json

Development

To modify or extend the server:

# Install dependencies
npm install

# Build and run
npm run build
npm start

# Development mode with auto-rebuild
npm run dev

Project Structure

fatsecret-mcp/
├── src/
│   ├── index.ts        # Main MCP server implementation
│   └── cli.ts          # OAuth console utility
├── dist/               # Compiled JavaScript files
├── test-*.js           # Test utilities
├── package.json
├── tsconfig.json
└── README.md

License

MIT License - see LICENSE file for details.