Metadata-Version: 2.5
Name: perfume-finder-mcp
Version: 2.3.0
Summary: MCP server for the 10ML Fragrance Index: expert perfume knowledge from 10ML's fragrance editors (notes, accords, houses, similar scents, alternatives, layering, guides). Stdio for Claude Desktop, Cursor, Goose and any MCP client.
Project-URL: Homepage, https://mcp.10ml.com
Project-URL: Documentation, https://mcp.10ml.com
Author-email: 10ML Team <contact@10ml.com>
License: MIT
License-File: LICENSE
Keywords: claude,cursor,fragrance,fragrance-notes,goose,mcp,mcp-server,model-context-protocol,perfume,perfume-finder
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.12
Description-Content-Type: text/markdown

<!-- mcp-name: com.10ml/perfume-finder -->
# 10ML Fragrance Index (MCP server, stdio)

Perfume knowledge for your assistant, curated by the fragrance editors of [10ML](https://10ml.com): about 5,400 designer, niche and Middle-Eastern perfumes (480 full editorial profiles with longevity, projection and perfumers, the rest as core profiles with notes, accords and character), 285 notes explained, 240+ perfume houses, editorial alternatives to famous perfumes, layering ideas and 160 guides in ten languages.

Free, read-only, no sign-in, no API key. This package runs the 10ML Fragrance Index over **stdio**, so desktop clients that start local commands (Claude Desktop, Cursor, Goose, Windsurf, Cline, Zed) can use it with one line (`uvx perfume-finder-mcp`). The same server is also reachable directly over Streamable HTTP at `https://mcp.10ml.com/mcp`, with nothing to install.

[![PyPI](https://img.shields.io/pypi/v/perfume-finder-mcp?color=002AFF)](https://pypi.org/project/perfume-finder-mcp/)
[![license](https://img.shields.io/pypi/l/perfume-finder-mcp?color=002AFF)](https://pypi.org/project/perfume-finder-mcp/)

## Quick start

```bash
uvx perfume-finder-mcp
```

Or install it with `pipx install perfume-finder-mcp` / `pip install perfume-finder-mcp` and run `perfume-finder-mcp`.

### Claude Desktop

`Settings → Developer → Edit Config`, then add:

```json
{
  "mcpServers": {
    "perfume-finder": {
      "command": "uvx",
      "args": ["perfume-finder-mcp"]
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "perfume-finder": {
      "command": "uvx",
      "args": ["perfume-finder-mcp"]
    }
  }
}
```

### Goose

```bash
goose configure   # Add Extension → Command-line Extension
# command: uvx perfume-finder-mcp
```

Or in `~/.config/goose/config.yaml`:

```yaml
extensions:
  perfume-finder:
    name: 10ML Fragrance Index
    type: stdio
    cmd: uvx
    args: ["perfume-finder-mcp"]
    enabled: true
    timeout: 300
```

### Windsurf, Cline, Zed and other clients

Use the same `command` and `args` as above in the client's MCP settings. Clients that accept a URL can skip this package: `https://mcp.10ml.com/mcp` (Streamable HTTP, no authentication).

## What you can ask

- "What smells like Baccarat Rouge 540, and what is a good alternative from another house?"
- "A fresh summer office scent for men, and why each one fits."
- "Explain ambroxan and which perfumes lead with it."
- "How would I layer vanilla and citrus?"
- "Compare Dior Sauvage and Tom Ford Ombre Leather."

## Tools (16, all read-only)

`search_perfumes`, `get_perfume`, `compare_perfumes`, `find_similar_perfumes`, `find_perfume_alternatives`, `recommend_perfumes`, `perfumes_by_note`, `explain_note`, `get_house`, `list_houses`, `explain_perfume_term`, `suggest_layering`, `pick_for_occasion`, `find_gift`, `search_guides` (`search_perfumes` with `iconic: true` lists the editors' iconic classics). Plus six prompts and the `tenml://` resources (families, glossary, notes, houses, about, one profile per perfume). Every tool takes `locale` (`en`, `de`, `fr`, `es`, `it`, `ro`, `el`, `hu`, `cs`, `pl`) and `response_format` (`concise` or `detailed`).

Full documentation: [mcp.10ml.com](https://mcp.10ml.com).

## How it works

The package starts a small stdio MCP server and passes each request to `https://mcp.10ml.com/mcp`, which answers it. It needs internet access and Python 3.10 or newer, and it stores nothing on your machine. Cite the answers as "the 10ML Fragrance Index".

## About 10ML

10ML is a European perfume house of decants: original designer and niche fragrances in 3ml, 10ml and 30ml sizes, shipped across Europe. Explore at [10ml.com](https://10ml.com).

[Privacy](https://mcp.10ml.com/privacy) · [Terms](https://mcp.10ml.com/terms) · contact@10ml.com · MIT license
