Metadata-Version: 2.5
Name: perfume-finder-mcp
Version: 2.3.1
Summary: 10ML Perfume Finder: the free perfume MCP server and fragrance API for AI assistants. 5,400+ perfumes and 249 houses from the 10ML Fragrance Index with note pyramids, accords, similar scents and alternatives. 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: ai-assistant,chatgpt,claude,cursor,fragrance,fragrance-api,fragrance-notes,fragrance-notes-api,fragrantica-alternative,goose,mcp,mcp-server,model-context-protocol,perfume,perfume-api,perfume-database,perfume-finder,perfume-mcp
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 Perfume Finder (perfume MCP server, stdio)

10ML Perfume Finder is the free perfume MCP server and fragrance API, powered by the 10ML Fragrance Index and curated by the fragrance editors of [10ML](https://10ml.com): 5,400+ designer, niche and Middle-Eastern perfumes and 249 houses (481 full editorial profiles with longevity, projection and perfumers, the rest as core profiles with notes, accords and character), 285 notes explained, editorial alternatives to famous perfumes, layering ideas and 164 guides in ten languages. In our 20-question agent test (October 2026) it answered all 20, one call each, at a median of about 0.3 seconds.

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
