# Perfume API & Fragrance MCP (No Key) (`10ml/10ml-perfume-finder`) Actor

The free perfume MCP server and fragrance API, powered by the 10ML Fragrance Index: note pyramids, accords, similar scents and alternatives. No key.

- **URL**: https://apify.com/10ml/10ml-perfume-finder.md
- **Developed by:** [10ML](https://apify.com/10ml) (community)
- **Categories:** Developer tools, MCP servers, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 10ML Perfume Finder

**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+ perfumes and 249 houses with note pyramids, accords, families, similar scents and alternatives. No API key, no sign-up.

In our 40-question benchmark of free, no-key perfume MCP servers (20 October 2026) it was the most accurate and the fastest: 39 of 40 correct, one call per question, median 232 ms. See the [method and results](https://10ml.com/perfume-mcp-servers-compared).

This Actor puts the fragrance API on Apify. Give it a perfume, a note, a house or a free-text description, and it returns clean, structured JSON records, ready for spreadsheets, pipelines, recommendation tools and assistants.

### What you get

- **Perfume profiles**: house, launch year, audience, concentration, fragrance family, accords, the note pyramid (top, heart and base), best seasons and occasions, an editorial character line and links to 10ml.com guides. The 481 full editorial profiles add longevity, projection and perfumers.
- **Similar scents**: perfumes ranked by shared notes, accords and style, each with how close it is (very close, similar vibe, same spirit), the notes it shares and a one-line reason.
- **Notes explained**: what a note smells like, its family, origin, mood, what it pairs with and the perfumes it defines. 285 notes.
- **Houses**: country, type, founding year, what each house is known for and its signature perfumes.
- **Ten languages**: links and labels in English, German, French, Spanish, Italian, Romanian, Greek, Hungarian, Czech and Polish. Note names in other languages are understood too: Vanille finds vanilla.

### Modes

| Mode | Query | Returns |
|---|---|---|
| `search` | Free text: "fresh citrus summer for men", "Tom Ford tobacco", "vanilla gourmand for winter" | Ranked perfumes with note pyramids |
| `perfume` | A perfume name: "Baccarat Rouge 540" | The full profile of one perfume, with its house, similar perfumes, alternatives and guides |
| `similar` | A perfume name | Perfumes that smell like it, with closeness and shared notes |
| `note` | A note: "vanilla", "oud" | The note explained, plus the perfumes it leads |
| `house` | A house: "Dior" (leave empty to list houses) | The house and its signature perfumes |

### Input

```json
{
  "mode": "similar",
  "query": "Baccarat Rouge 540",
  "language": "en",
  "limit": 10
}
```

- `mode`: one of `search`, `perfume`, `similar`, `note`, `house`.
- `query`: see the table above.
- `language`: `en`, `de`, `fr`, `es`, `it`, `ro`, `el`, `hu`, `cs` or `pl`.
- `limit`: 1 to 100 results for `search`, `similar` and the house list.

The Actor makes polite, sequential requests (one at a time, with a short pause), so large limits take a few seconds.

### Example output

Mode `search`, query `fresh citrus summer scent for men`:

```json
{
  "type": "perfume",
  "name": "Ciao Citrus",
  "house": "Paris Corner",
  "gender": "unisex",
  "family": "Citrus floral",
  "accords": ["citrus", "fresh", "white floral", "musky", "sandalwood", "amber"],
  "keyNotes": ["orange blossom", "lily of the valley", "musk", "sandalwood", "grapefruit"],
  "pyramid": {
    "top": ["grapefruit", "bergamot", "ginger candy accord"],
    "heart": ["orange blossom", "lily of the valley"],
    "base": ["musk", "sandalwood", "amber"]
  },
  "character": "Grapefruit and bergamot over orange blossom and lily of the valley, drying to musk, sandalwood and amber.",
  "url": "https://10ml.com/search?q=Paris%20Corner%20Ciao%20Citrus"
}
```

Mode `similar`, query `Baccarat Rouge 540`:

```json
{
  "type": "similar",
  "name": "Adwaa Al Sharq",
  "house": "Afnan",
  "closeness": "very close",
  "sharedNotes": ["saffron", "jasmine", "amberwood", "ambergris", "fir resin", "cedar"],
  "why": "shares saffron, jasmine, amberwood, ambergris"
}
```

Mode `note`, query `vanilla`:

```json
{
  "type": "note",
  "name": "vanilla",
  "family": "gourmand",
  "smellsLike": "Warm, creamy, sweet and comforting, like custard and cured pods.",
  "pairsWith": ["tonka bean", "amber", "sandalwood", "tobacco", "caramel", "patchouli"],
  "famousPerfumes": [{ "name": "Aventus", "house": "Creed", "year": 2010 }]
}
```

When nothing matches, the output holds one `not_found` record with a message and the closest suggestions.

### Use it from code

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('10ml/10ml-perfume-finder').call({
  mode: 'similar',
  query: 'Baccarat Rouge 540',
  limit: 10,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

### Also available as an MCP server and a REST API

The same answers are free outside Apify, with no key:

- MCP server (Streamable HTTP): `https://mcp.10ml.com/mcp`, for Claude, ChatGPT, Cursor, VS Code, Windsurf, Cline, Goose and Zed.
- REST API with an OpenAPI 3.1 description: `https://mcp.10ml.com/api/v1` and `https://mcp.10ml.com/openapi.json`.
- Home page, install guides and examples: [mcp.10ml.com](https://mcp.10ml.com).
- Perfume API overview and endpoints: [10ml.com/perfume-api](https://10ml.com/perfume-api).

### FAQ

**Is there a free perfume API?** Yes. The 10ML Fragrance Index API is a free perfume API and fragrance notes API: JSON over GET with an OpenAPI description, no key and no sign-up ([overview](https://10ml.com/perfume-api)). This Actor wraps it for Apify.

**Do I need an account with 10ML or an API key?** No.

**How should I cite it?** Cite the tool as "10ML Perfume Finder" and the data as "the 10ML Fragrance Index".

***

Made by [10ML](https://10ml.com).

# Actor input Schema

## `mode` (type: `string`):

What to look up: search perfumes, one perfume, similar scents, a fragrance note, or a perfume house.

## `query` (type: `string`):

Search: free text such as 'fresh citrus summer for men' or 'Tom Ford tobacco'. Perfume and Similar scents: a perfume name, for example 'Baccarat Rouge 540'. Note: a note name such as 'vanilla' or 'oud'. House: a house name such as 'Dior'; leave empty in House mode to list houses.

## `language` (type: `string`):

Language of the 10ml.com links and labels. Perfume, house and note names stay as they are.

## `limit` (type: `integer`):

Maximum number of results for Search, Similar scents and House listing.

## Actor input object example

```json
{
  "mode": "search",
  "query": "fresh citrus summer scent for men",
  "language": "en",
  "limit": 10
}
```

# Actor output Schema

## `results` (type: `string`):

Every record the lookup returned.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "fresh citrus summer scent for men"
};

// Run the Actor and wait for it to finish
const run = await client.actor("10ml/10ml-perfume-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "query": "fresh citrus summer scent for men" }

# Run the Actor and wait for it to finish
run = client.actor("10ml/10ml-perfume-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "fresh citrus summer scent for men"
}' |
apify call 10ml/10ml-perfume-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,10ml/10ml-perfume-finder"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/19duzsXzNtXkHALqi/builds/3gBN1WASlS9PcT1CM/openapi.json