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, weight tracking, and add entries
Secure Credential Storage: Encrypted storage of API credentials and tokens

Not Yet Implemented (Requires OAuth 2.0)

The following features require OAuth 2.0 authentication which is not yet supported:

foods.autocomplete — Food name autocomplete suggestions
food.find_id_for_barcode — Barcode scanning lookup

Getting Started

Prerequisites

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

Installation

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

# Install dependencies
npm install

# Build the TypeScript
npm run build

Setup

1. Get FatSecret API Credentials

Visit the FatSecret Platform
Create a developer account and register your application
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:

Ask for your Client ID and Client Secret
Save them securely in ~/.fatsecret-mcp-config.json
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):

Set your API credentials:

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

Start the OAuth flow:

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

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

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
foodName (string, required): Name/description of the food item
servingId (string, required): Serving ID for the food
quantity (number, required): Quantity of the serving
mealType (string, required): Meal type (breakfast, lunch, dinner, other)
date (string, optional): Date in YYYY-MM-DD format (default: today)

`edit_food_entry`

Edit an existing food diary entry.

Parameters:

foodEntryId (string, required): The food entry ID to edit
foodName (string, optional): New name/description
servingId (string, optional): New serving ID
quantity (number, optional): New quantity
mealType (string, optional): New meal type (breakfast, lunch, dinner, other)

`delete_food_entry`

Delete a food diary entry.

Parameters:

foodEntryId (string, required): The food entry ID to delete

`get_food_entries_month`

Get summary of user's food diary entries for a month.

Parameters:

date (string, optional): Date in YYYY-MM-DD format to specify the month (default: current month)

`get_weight_month`

Get user's weight entries for a specific month.

Parameters:

date (string, optional): Date in YYYY-MM-DD format to specify the month (default: current month)

`update_weight`

Add or update a weight entry.

Parameters:

currentWeightKg (number, required): Current weight in kilograms
date (string, optional): Date in YYYY-MM-DD format (default: today)
goalWeightKg (number, optional): Goal weight in kilograms
comment (string, optional): Optional comment for the weight entry

Example Workflow

Setup Credentials:

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

Search for Foods:

Tool: search_foods
- searchExpression: "chicken breast"

Get Food Details:
```
Tool: get_food
- foodId: "12345"
```

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"

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:

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

Unit Tests

Unit tests use mocked HTTP requests and don't require API credentials.

npm test              # Watch mode
npm run test:run      # Single run
npm run test:coverage # With coverage report

Test structure:

src/__tests__/
├── oauth/           # OAuth signature and request tests
├── utils/           # Utility functions (encoding, date)
├── methods/         # API method tests
├── schemas/         # Zod validation schema tests
├── integration/     # Integration tests (real API)
└── client.test.ts   # FatSecret client tests

Integration Tests

Integration tests call the real FatSecret API and verify actual responses.

Setup credentials:

Create a .env file in the project root:

# Required for public API methods (foods, recipes)
FATSECRET_CLIENT_ID=your_client_id
FATSECRET_CLIENT_SECRET=your_client_secret

# Required for authenticated methods (profile, diary, weight)
FATSECRET_ACCESS_TOKEN=user_access_token
FATSECRET_ACCESS_TOKEN_SECRET=user_access_token_secret

Run integration tests:

npm run test:integration

Test coverage:

Module	Methods	Tests
Foods	`searchFoods`, `getFood`	9
Recipes	`searchRecipes`, `getRecipe`	11
Profile	`getProfile`	5
Diary	`getFoodEntries`, `createFoodEntry`, `editFoodEntry`, `deleteFoodEntry`, `getFoodEntriesMonth`	16
Weight	`getWeightMonth`, `updateWeight`	12

Notes:

Tests are automatically skipped when credentials are not available
createFoodEntry tests create real entries in your FatSecret diary
Integration tests have a 30-second timeout for API calls

Testing in Claude Desktop

Restart Claude Desktop after configuring the MCP server
Look for "fatsecret" in the available tools
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
│   ├── client.ts       # FatSecret API client
│   ├── methods/        # API method implementations
│   ├── oauth/          # OAuth 1.0a implementation
│   ├── schemas/        # Zod validation schemas
│   ├── utils/          # Utility functions
│   └── __tests__/      # Unit and integration tests
├── dist/               # Compiled JavaScript files
├── package.json
├── tsconfig.json
└── README.md

Credits

Originally created by Felipe Coury. Now maintained by Dmitry Sinev.

License

MIT License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.claude		.claude
src		src
utils		utils
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
todo.md		todo.md
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

FatSecret MCP Server

Features

Not Yet Implemented (Requires OAuth 2.0)

Getting Started

Prerequisites

Installation

Setup

1. Get FatSecret API Credentials

2. Configure the MCP Server

3. Authentication Process

Option 1: Using the OAuth Console Utility (Recommended)

Option 2: Manual Authentication via MCP Tools

Option 3: Using Environment Variables

Usage

1. Set API Credentials

2. Authenticate a User (3-Legged OAuth)

3. Use the API

Food Search and Information

Recipe Search and Information

User Data (Requires Authentication)

Utility

Available Tools

Authentication Tools

set_credentials

start_oauth_flow

complete_oauth_flow

check_auth_status

Food Database Tools

search_foods

get_food

Recipe Database Tools

search_recipes

get_recipe

User Data Tools (Requires Authentication)

get_user_profile

get_user_food_entries

add_food_entry

edit_food_entry

delete_food_entry

get_food_entries_month

get_weight_month

update_weight

Example Workflow

Configuration Storage

Security Notes

API Reference

Error Handling

Testing

Unit Tests

Integration Tests

Testing in Claude Desktop

Troubleshooting

Common Issues

"Invalid integer value: date"

OAuth Authentication Fails

Server Not Found in Claude

"User authentication required"

Development

Project Structure

Credits

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`set_credentials`

`start_oauth_flow`

`complete_oauth_flow`

`check_auth_status`

`search_foods`

`get_food`

`search_recipes`

`get_recipe`

`get_user_profile`

`get_user_food_entries`

`add_food_entry`

`edit_food_entry`

`delete_food_entry`

`get_food_entries_month`

`get_weight_month`

`update_weight`

Packages