langchain-10ml-perfume: LangChain tools for the free 10ML Perfume Finder

LangChain tools for the free perfume API and fragrance notes API behind 10ML Perfume Finder: 6,000+ perfumes from the 10ML Fragrance Index, curated by the fragrance editors of 10ML, with note pyramids, accords, similar scents, alternatives, notes explained and houses. Read-only, no API key, no sign-up. Depends on langchain-core only.

Install

pip install langchain-10ml-perfume

Python 3.10 or newer.

Quick start

from langchain_10ml_perfume import Perfume10MLToolkit

tools = Perfume10MLToolkit().get_tools()  # 8 tools, no key needed

search = next(t for t in tools if t.name == "search_perfumes")
found = search.invoke({"query": "fresh citrus summer cologne for men", "limit": 3})
for hit in found["results"]:
    print(hit["name"], "-", hit["house"])

Give the tools to an agent:

from langchain.agents import create_agent

agent = create_agent("anthropic:claude-sonnet-4-5", tools)
result = agent.invoke({"messages": [("user", "Find me an alternative to Baccarat Rouge 540 and tell me how close it is.")]})
print(result["messages"][-1].content)

Or use a single tool:

from langchain_10ml_perfume import FindPerfumeAlternativesTool

print(FindPerfumeAlternativesTool().invoke({"perfume": "Creed Aventus", "limit": 3}))

Tools

Every tool has a typed pydantic input schema (enums for audience, season, occasion, style, closeness, locale), a description written for tool-calling models, an async ainvoke, and handle_tool_error=True, so an API error comes back to the agent as text. An unknown perfume returns found: false with spelling suggestions instead of raising. Results are paginated: pass next_cursor back as cursor.

Perfume10MLToolkit(base_url=..., timeout=...) points the tools at another API root or changes the 15 second timeout.

What comes back

Plain JSON, as the REST API sends it. For example find_perfume_alternatives returns original, alternatives[] (each with closeness and why it fits) and total; explain_note returns found and a note with smells_like, family, origin and pairings. Perfume entries include house, family, accords, key notes and links to 10ml.com guides.

Also available

• MCP server for Claude, ChatGPT, Cursor and more: https://10ml.com/perfume-mcp-server (https://mcp.10ml.com/mcp, or uvx perfume-mcp)
• Typed REST client without LangChain: pip install perfume-api
• OpenAPI 3.1: https://mcp.10ml.com/openapi.json

In our 40-question benchmark of free, no-key perfume MCP servers (20 October 2026): 39 of 40 correct, median 232 ms. Read the benchmark.

Develop

pip install -e ".[test]"
pytest                # unit tests, HTTP mocked
pytest -m live        # optional smoke test against https://mcp.10ml.com

Cite as

Cite the answers as "the 10ML Fragrance Index", curated by the fragrance editors of 10ML.

10ml.com/perfume-mcp-server · 10ml.com/perfume-api · Privacy · Terms · contact@10ml.com

License

MIT.