victualia-mcp by dagnele - MCP Server

victualia-mcp

An MCP (Model Context Protocol) server for the Victualia API.

What is Victualia?

Victualia - Your Home, Organized

Victualia is a lifestyle application that helps you organize your home, track household items, plan meals, and manage your life efficiently. Available on Web, iOS, and Android.

Key Features

Home Inventory Tracking - Track everything from pantry to garage
Barcode Scanning - Quickly add items using the Open Food Facts database
AI-Powered Meal Planning - Get personalized meal suggestions based on your preferences and available ingredients
Auto-Generated Shopping Lists - Never forget what you need
Recipe Management & Import - Import recipes from any website or create your own
Expiry Date Alerts - Reduce food waste with timely notifications
Multi-Home Support - Manage multiple properties from one account
Multi-Location Organization - Organize items by location (pantry, fridge, garage, etc.)

Supported Languages

English, Spanish, Italian, German, French, and Portuguese.

What Does This MCP Server Do?

This server dynamically fetches the OpenAPI specification from Victualia and exposes all API endpoints as MCP tools, allowing AI assistants (Claude, OpenCode, Cursor, etc.) to interact with the Victualia API on your behalf.

With this MCP server, you can ask your AI assistant to:

Check what items are in your pantry
Add items to your shopping list
Get meal plan suggestions
Track expiring items
Manage your recipes
And more!

Installation Options

Option 1: npx (Recommended - No Installation)

VICTUALIA_API_KEY=your-api-key npx victualia-mcp

Option 2: Global npm Install

npm install -g victualia-mcp
victualia-mcp

Option 3: Standalone Binary

Download the pre-built binary for your platform from the Releases page:

Platform	Binary
Linux (x64)	`victualia-mcp-linux-x64`
macOS (Intel)	`victualia-mcp-darwin-x64`
macOS (Apple Silicon)	`victualia-mcp-darwin-arm64`
Windows (x64)	`victualia-mcp-windows-x64.exe`

# Linux/macOS
chmod +x victualia-mcp-linux-x64
./victualia-mcp-linux-x64

# Windows
victualia-mcp-windows-x64.exe

Option 4: Docker

docker run -e VICTUALIA_API_KEY=your-api-key ghcr.io/dagnele/victualia-mcp:latest

Or with Docker Compose:

services:
  victualia-mcp:
    image: ghcr.io/dagnele/victualia-mcp:latest
    environment:
      - VICTUALIA_API_KEY=your-api-key

Getting Your API Key

API access requires a Premium account (€9.99/month).

To get your API key:

Go to victualia.app and sign up or log in
Subscribe to the Premium plan
Navigate to Settings > API Keys
Generate a new API key and copy it

Keep your API key secure and never share it publicly.

Configuration

The server is configured via environment variables:

Variable	Description	Default
`VICTUALIA_API_KEY`	API key for authentication	(required)
`VICTUALIA_API_URL`	Base URL for API requests	`https://www.victualia.app/api/v1`
`VICTUALIA_OPENAPI_URL`	URL to fetch OpenAPI spec	`https://www.victualia.app/api/v1/openapi.json`

Usage with AI Assistants

Claude Desktop

Add to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "victualia": {
      "command": "npx",
      "args": ["-y", "victualia-mcp"],
      "env": {
        "VICTUALIA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Or using the standalone binary:

{
  "mcpServers": {
    "victualia": {
      "command": "/path/to/victualia-mcp-linux-x64",
      "env": {
        "VICTUALIA_API_KEY": "your-api-key-here"
      }
    }
  }
}

OpenCode

Add to your opencode.json:

{
  "mcp": {
    "victualia": {
      "command": "npx",
      "args": ["-y", "victualia-mcp"],
      "env": {
        "VICTUALIA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "victualia": {
      "command": "npx",
      "args": ["-y", "victualia-mcp"],
      "env": {
        "VICTUALIA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Built-in Tools

In addition to the dynamically generated API tools, the server provides:

Tool	Description
`list_endpoints`	List all available Victualia API endpoints
`api_info`	Get information about the Victualia API

How It Works

On startup, the server fetches the OpenAPI specification from Victualia
Each API endpoint is converted into an MCP tool with:
- The operation ID as the tool name
- Path, query, and header parameters as tool arguments
- Request body support for POST/PUT/PATCH methods
When a tool is called, the server makes the corresponding HTTP request to the Victualia API
Responses are returned as JSON

Development

Requirements

Bun v1.0.0 or later

Setup

git clone https://github.com/dagnele/victualia-mcp.git
cd victualia-mcp
bun install

Commands

# Run in development mode with hot reload
bun run dev

# Type check
bun run typecheck

# Build for npm distribution
bun run build

# Build standalone binary (current platform)
bun run build:binary

# Build binaries for all platforms
bun run build:all

# Run locally
bun start

Docker Build

docker build -t victualia-mcp .
docker run -e VICTUALIA_API_KEY=your-key victualia-mcp

Publishing

Automated Releases

Publishing happens automatically when you push a version tag:

git tag v1.0.0
git push origin v1.0.0

This will:

Build binaries for all platforms
Publish to npm
Push Docker image to GitHub Container Registry
Create a GitHub Release with binary downloads

Manual Publishing

npm publish

GitHub Actions Setup

To enable automated releases, add these secrets to your repository:

Secret	Description
`NPM_TOKEN`	npm access token for publishing
`DOCKERHUB_USERNAME`	(Optional) Docker Hub username
`DOCKERHUB_TOKEN`	(Optional) Docker Hub access token

License

MIT