Repository avatar
Databases
v0.3.1
active

parfumo-mcp

io.github.hessbey/parfumo-mcp

Parfumo MCP server: fragrance database, collection, wear log, ratings and reviews. Unofficial.

Documentation

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:

    BinaryTransportFor
    parfumo-mcpstdioOne person, on their own machine. Nothing to host, no OAuth
    parfumo-mcp-serverStreamable HTTPSeveral 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.

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

AreaToolsAccount needed
Databasesearch, perfume page, reviews, statements, similar perfumes, brand, perfumer, note, rankings, page fetchNo
Collectionlist, read, add, move, update, remove, custom lists, CSV export, statisticsYes
Wear loglog, list, deleteYes
Ratings and reviewsrate, classify, write or delete a review or statement, list your ownYes
Socialmember profiles, messages, notifications, follows, wall, forum, blogs, Souk, communitiesReads: mostly no. Writes: yes
Profile and accountprofile, settings, session statusYes

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

GuideContents
Local usageThe stdio binary: account, client setup, local files
HostingThe HTTP server: Docker, users, OAuth, linking a Parfumo account
ConfigurationEvery environment variable; public-write lock, caps and recipients
Tool catalogThe 48 tools, conventions, error codes
Project statusWhat is proven against the real site, what is not, what is left to do
All documentsIndex, 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

NPM
parfumo-mcp
Install Command
npm install parfumo-mcp