blue-perfumery

Blue Perfumery MCP Server provides Claude and other MCP-compatible assistants with direct access to Blue Perfumery's perfume catalog and related product information. The server exposes a set of tools that let you list all perfumes, fetch a specific perfume by ID, search by name or brand, filter by category (men, women, niche), and obtain a purchase link for a perfume. You can interact with these tools by asking natural language questions or using explicit tool prompts; for example, you might ask Claude to list all perfumes, search for woody scents, or retrieve a purchase link for a particular bottle. The server is designed to securely query the MongoDB-backed product catalog and return structured results that can be presented in conversational or structured responses.

Available tools include:

• list_all_perfumes: Retrieve all perfumes in the collection.
• get_perfume_by_id: Retrieve a single perfume by its ID.
• search_perfumes: Search perfumes by name or brand.
• get_perfumes_by_category: Filter perfumes by category (men, women, niche).
• get_purchase_link: Retrieve a Shopier purchase link for a perfume.

To use with Claude Desktop, configure your Claude Desktop integration to point at this MCP server. For example, in claude_desktop_config.json, reference the server name and point the node process to the built dist index with the MONGODB_URI environment variable set appropriately. After configuration, ask Claude to perform queries like “Show me men’s fragrances” or “Get the purchase link for Acqua di Blue.”

Prerequisites

• Node.js 18+ installed on your machine
• npm (comes with Node.js) or pnpm/yarn as preferred
• MongoDB instance available (local or cloud) with a connection string

Installation and setup steps

1. Install dependencies

   npm install
   

2. Configure environment variables Create a .env file or set environment variables directly. At minimum, provide the MongoDB connection string:

   echo "MONGODB_URI=your-mongodb-uri" > .env
   

   Alternatively, set the variable in your environment:

   • Linux/macOS: export MONGODB_URI=your-mongodb-uri
   • Windows: set MONGODB_URI=your-mongodb-uri

3. Build the TypeScript project

   npm run build
   

4. Run the MCP server

   npm start
   

Optional development workflow

• Run in development with tsx (hot-reloading):

  npm run dev
  

• If you prefer a different runtime, ensure the entry point compiles to dist/index.js and update the mcp_config accordingly.

Note: If you’re integrating with Claude Desktop, ensure claude_desktop_config.json points to the server and includes the MONGODB_URI in the env section as shown in the example configuration.

Tips and common considerations:

• Ensure your MongoDB deployment is accessible from the server host and that the URI in MONGODB_URI is correct.
• Keep your MongoDB credentials secure; avoid committing them to version control.
• The server assumes a MongoDB-backed Product model consistent with the provided structure (src/models/Product.ts). If you customize fields, update the model accordingly.
• When deploying, consider securing the MCP endpoint and applying access control if exposing to external assistants.
• If you encounter connection errors, verify network access, MongoDB user permissions, and that the database name matches your deployment.
• For Claude Desktop integration, use the server name (blue-perfumery) and ensure the path to dist/index.js is correct after building.
• If you add or modify tools, update any API surface or documentation accordingly to keep user prompts aligned with available capabilities.