
parfumo-mcp
io.github.hessbey/parfumo-mcp
Parfumo MCP server: fragrance database, collection, wear log, ratings and reviews. Unofficial.
Documentation
parfumo-mcp
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-mcpstdio One person, on their own machine. Nothing to host, no OAuth parfumo-mcp-serverStreamable HTTP Several people, isolated accounts, on a server behind HTTPS (Docker image) -
Safe by default. Every write tool supports
dry_runand 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 --writesshows 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 sitewww.parfumo.deuses 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
/linkpage (HTTP) — are encrypted at rest with AES-256-GCM, and never appear in logs, errors or tool results.
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
parfumo-mcpnpm install parfumo-mcp