Content
# Melchior MCP
A tiny [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
real-time contents of your [Melchior](https://compte.melchior.pro) connected fridge to any
MCP-compatible client (Claude Code, Claude Desktop, etc.).
It ships a single, **read-only** tool:
| Tool | Description |
| --- | --- |
| `get_fridge` | Returns what's currently in your fridge, grouped by category (Plats / Desserts / Autres) with the quantity of each item. |
## How it works
The server logs into `compte.melchior.pro` with your account (the same Laravel CSRF +
`ajax_login` handshake the website uses), scrapes the `/mon-frigo` page, and parses it into
structured JSON. A single HTTP client keeps the session cookie alive between calls and only
re-authenticates when the session has expired (~2h).
Example output:
```json
{
"source": "https://compte.melchior.pro/mon-frigo",
"total_items": 12,
"categories": [
{
"category": "Plats",
"items": [
{ "name": "Poulet Romarin", "quantity": 3 },
{ "name": "Poulet Curry", "quantity": 2 }
]
}
]
}
```
## Requirements
- [uv](https://docs.astral.sh/uv/) (handles Python and dependencies automatically via the
inline script metadata at the top of `melchior_mcp.py`)
- A Melchior account
No manual `pip install` needed — `uv run` reads the `# /// script` block and installs
`mcp`, `httpx`, and `beautifulsoup4` in an isolated environment on first run.
## Configuration
Credentials are read from two environment variables — **never hard-coded**:
| Variable | Description |
| --- | --- |
| `MELCHIOR_EMAIL` | Your Melchior account email |
| `MELCHIOR_PASSWORD` | Your Melchior account password |
Copy `.env.example` to `.env` and fill in your values (the `.env` file is git-ignored), or
pass them directly in your MCP client configuration (see below).
## Quick self-test
Run the server once outside of any MCP transport — it prints the fridge as JSON and exits:
```bash
MELCHIOR_EMAIL="you@example.com" MELCHIOR_PASSWORD="..." uv run melchior_mcp.py selftest
```
On Windows PowerShell:
```powershell
$env:MELCHIOR_EMAIL="you@example.com"; $env:MELCHIOR_PASSWORD="..."; uv run melchior_mcp.py selftest
```
## Use with Claude Code
Add the server to your MCP configuration (adjust the absolute paths to where you cloned the
repo):
```json
{
"mcpServers": {
"melchior": {
"type": "stdio",
"command": "uv",
"args": ["run", "--quiet", "/absolute/path/to/melchior-mcp/melchior_mcp.py"],
"env": {
"MELCHIOR_EMAIL": "you@example.com",
"MELCHIOR_PASSWORD": "your-password-here"
}
}
}
}
```
Or with the CLI:
```bash
claude mcp add melchior \
--env MELCHIOR_EMAIL=you@example.com \
--env MELCHIOR_PASSWORD=your-password-here \
-- uv run --quiet /absolute/path/to/melchior-mcp/melchior_mcp.py
```
Then ask your assistant: *"What's in my fridge?"* 🧊
## Notes
- This is an unofficial project and is not affiliated with Melchior.
- It relies on the current HTML layout of `/mon-frigo`; if the site changes, the parser in
`_parse_fridge()` may need an update.
## License
MIT — see [LICENSE](LICENSE).
