Skip to main content
Glama
Parfumo MCP Server

Parfumo MCP Server

by hessbey

parfumo-mcp

English · Français · Deutsch

ci license: MIT rust 1.90+

Parfumo MCP server: a Model Context Protocol server, written in Rust, that gives an AI assistant access to Parfumo: the fragrance database, your collection, wear log, ratings and reviews, and the community side (messages, forum, blogs, Souk).

Unofficial. This project is not affiliated with or endorsed by Parfumo. It reads the same pages a browser does and, for an account linked with its password, the interface of Parfumo's own application, at one request per second. Automated access may still lead Parfumo to suspend the linked account — use it at your own risk.

What you get

  • 48 tools, all prefixed parfumo_. The 10 database tools and the public reads (forum, blogs, Souk, profiles) work without a Parfumo account.

  • Two binaries, same tools:

    Binary

    Transport

    For

    parfumo-mcp

    stdio

    One person, on their own machine. Nothing to host, no OAuth

    parfumo-mcp-server

    Streamable HTTP

    Several people, isolated accounts, on a server behind HTTPS (Docker image)

  • Safe by default. Every write tool supports dry_run and reads the real state back. Anything other members can see stays in dry-run until you turn public writes on, and is then capped per tool and per day.

  • Auditable. Every tool call is logged locally; parfumo-mcp audit --writes shows what was really written to your account.

  • Always current. Every read asks Parfumo: no page is kept to be served again later.

  • Richer answers with an account linked by password. When your Parfumo account is linked with its nickname or e-mail and its password, part of the database reads (search, perfume, brand, perfumer, release year, similar perfumes) go through the interface Parfumo's own application uses. Search results then give each perfume's rating and number of ratings, and a search by name, brand or year is no longer limited to 1000 results. Nothing else changes: with an account linked by a browser cookie, or with no account, everything keeps working through the web pages.

  • Careful with the site. One request per second per user, random jitter, a fixed and honest User-Agent. No captcha solving, no Cloudflare bypass.

  • Targets www.parfumo.com, the English site. The German site www.parfumo.de uses different URLs and labels and is not supported.

  • Secrets stay out of the conversation. Credentials are typed on a login page — on your own computer (stdio) or on the server's /link page (HTTP) — are encrypted at rest with AES-256-GCM, and never appear in logs, errors or tool results.

Related MCP server: Google Photos MCP Server

Quick start (local)

With Node.js installed, there is nothing to download: npx fetches the program for your system (Linux, macOS or Windows). Add it to Claude Code:

claude mcp add parfumo -- npx -y parfumo-mcp

Or to any client configured with a JSON file (Claude Desktop and most others):

{
  "mcpServers": {
    "parfumo": { "command": "npx", "args": ["-y", "parfumo-mcp"] }
  }
}

That is all: the public tools work at once. The first time a tool needs your Parfumo account, the assistant gives you the link of a login page on your own computer; or open it yourself with npx -y parfumo-mcp login. Your password is typed there, never in the conversation, and is stored encrypted on your computer.

Without Node.js, download the program from the latest release and give the client its path instead. Details: Local usage.

To host it for several people, see Hosting: the server is published as a Docker image, ghcr.io/hessbey/parfumo-mcp-server.

Tools

Area

Tools

Account needed

Database

search, perfume page, reviews, statements, similar perfumes, brand, perfumer, note, rankings, page fetch

No

Collection

list, read, add, move, update, remove, custom lists, CSV export, statistics

Yes

Wear log

log, list, delete

Yes

Ratings and reviews

rate, classify, write or delete a review or statement, list your own

Yes

Social

member profiles, messages, notifications, follows, wall, forum, blogs, Souk, communities

Reads: mostly no. Writes: yes

Profile and account

profile, settings, session status

Yes

Full list: Tool catalog.

A note on text

Parfumo forbids AI-generated text in reviews, statements, forum posts and messages, and restricts or deletes accounts that publish it. The tools that send text tell the assistant so: it should pass on your words, not write them for you.

Documentation

Guide

Contents

Local usage

The stdio binary: account, client setup, local files

Hosting

The HTTP server: Docker, users, OAuth, linking a Parfumo account

Configuration

Every environment variable; public-write lock, caps and recipients

Tool catalog

The 48 tools, conventions, error codes

Project status

What is proven against the real site, what is not, what is left to do

All documents

Index, including the in-depth references written in French

How it is built

crates/parfumo-client      library: access to the site. Transport, routes and selectors
                           (one module, src/site.rs), HTML parsing, the interface of
                           Parfumo's application (src/app*.rs), models
crates/parfumo-mcp-core    library: the 48 tools, Parfumo session, storage, audit log
crates/parfumo-mcp         local binary: the tools over stdio
crates/parfumo-mcp-server  hosted binary: the tools over HTTP, with OAuth, users, canary
npm/                       the npm packages that deliver the local binary (`npx parfumo-mcp`)

Parfumo is a server-rendered site with no public API, so the client parses HTML. All routes and selectors live in one module, the parsers are tested against recorded fixtures, and a daily read-only canary on the hosted server reports any page whose structure has changed. Since version 0.3.0, part of the database reads of an account linked with its password go through the JSON interface of Parfumo's own application, with that member's own session and nothing else; the web pages answer everything else, and everything when that interface cannot. It is described in Application interface; the canary checks it when its test account is linked that way.

Development

cargo test --workspace     # no network: recorded fixtures and local fake servers
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --check

CI runs all three on Linux, the tests again on macOS and Windows, builds the two release binaries, then builds the Docker image and checks its size, startup and idle memory. Pushing a tag vX.Y.Z publishes a release: binaries for five targets and the Docker image.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with Obsidian vaults for creating, reading, searching, and managing notes, daily notes, TODOs, session reports, and backlinks through both stdio and HTTP/SSE transports.
      10
      4
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables AI assistants to read upcoming, past, archived and manual flights, search flights, airports, airlines and aircraft, check status and radar data, and manage tracked flights, notes, seats and bookings through Flighty's API. Runs on Windows, macOS and Linux over stdio or streamable HTTP, with a token kept in your own setup and an optional read-only mode.
      48
      3
      MIT