# Algolia Mcp

> Search Algolia indices via the Algolia MCP server, retrieve analytics (top searches, no-result rates, click positions, user counts), and get product recommendations (bought-together, related, trending). Triggers on search, indexing, analytics, Algolia, recommendations, MCP.

- **Type:** Skill
- **Install:** `agentstack add skill-algolia-skills-algolia-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [algolia](https://agentstack.voostack.com/s/algolia)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [algolia](https://github.com/algolia)
- **Source:** https://github.com/algolia/skills/tree/main/skills/algolia-mcp

## Install

```sh
agentstack add skill-algolia-skills-algolia-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Algolia Search & Analytics

> **Need to write/modify data?** Use **algolia-cli** instead — it handles imports, exports, backups, settings changes, synonyms, rules, API keys, and all admin operations.

## Connection setup

Use `/algolia-mcp:mcp-connect` to configure the MCP client with the Algolia MCP server.
For manual client setup, see [connection-setup](references/connection-setup.md).

## Tool selection

### Search

| Task                   | Tool                              |
|------------------------|-----------------------------------|
| Search an index        | `algolia_search_index`            |
| List available indices | `algolia_search_list_indices`     |
| Explore facet values   | `algolia_search_for_facet_values` |

### Analytics

| Task                     | Tool                                            |
|--------------------------|-------------------------------------------------|
| Top searches             | `algolia_analytics_top_searches`                |
| Searches with no results | `algolia_analytics_searches_no_results`         |
| No-results rate          | `algolia_analytics_no_results_rate`             |
| Click positions          | `algolia_analytics_click_positions`             |
| No-click rate            | `algolia_analytics_no_click_rate`               |
| Searches without clicks  | `algolia_analytics_top_searches_without_clicks` |
| Search volume            | `algolia_analytics_number_of_searches`          |
| Top search results       | `algolia_analytics_top_search_results`          |
| Unique users             | `algolia_analytics_number_of_users`             |
| Top filters              | `algolia_analytics_top_filters`                 |
| Filters with no results  | `algolia_analytics_top_filters_no_results`      |
| Top countries            | `algolia_analytics_top_countries`               |

### Recommendations

| Task                       | Tool                      | `model` parameter  |
|----------------------------|---------------------------|--------------------|
| Frequently bought together | `algolia_recommendations` | `bought-together`  |
| Related products           | `algolia_recommendations` | `related-products` |
| Trending items             | `algolia_recommendations` | `trending-items`   |
| Trending facets            | `algolia_recommendations` | `trending-facets`  |
| Visually similar items     | `algolia_recommendations` | `looking-similar`  |

## Search Filter Syntax

Filters go in the `algolia_search_index` call alongside `query`:

**facetFilters** (array-based):
```
[["color:red", "color:blue"]]              → OR (red OR blue)
[["brand:Nike"], ["category:running"]]     → AND (Nike AND running)
[["size:10"], ["color:red", "color:blue"]] → mixed (size 10 AND (red OR blue))
```
Each inner array is OR'd; outer arrays are AND'd.

**numericFilters** (string-based):
```
["price = 50", "price = 1704067200"]`.

**Attribute selection**: Use `attributesToRetrieve: ["name", "price"]` to limit response size.

## Analytics Key Details

- **`clickAnalytics: true`**: Set this on `algolia_analytics_top_searches` or `algolia_analytics_top_search_results` to include CTR, conversion rate, and click count. Only these two tools support it.
- **`revenueAnalytics: true`**: Set on the same tools to also include add-to-cart rate, purchase rate, and revenue.
- **Data delay**: Recent data has a 1–4 hour processing delay. Use date ranges ending at least 4 hours ago for complete data.

### Interpreting Results

| No-results rate | Assessment |
|----------------|------------|
|  20% | Poor |

**Click positions**: Healthy = 30–40% of clicks at position 1, decreasing through 10. Even distribution = poor relevance. Concentrated at positions 5–10 = ranking issues.

**Low CTR + high search volume** = poor result relevance. Common causes: missing synonyms, content gaps, mismatched query intent.

## Recommendation Thresholds

| Threshold | Behavior |
|-----------|----------|
| 50 | More results, lower relevance |
| **60** | **Balanced (good default)** |
| 75 | Fewer results, higher relevance |

**Model parameter requirements**:
- `bought-together`, `related-products`, `looking-similar` → require `objectID`
- `trending-items` → does NOT require `objectID`. Use `facetName` + `facetValue` to filter by category
- `trending-facets` → requires `facetName`

## Required Workflow

1. **Discover first**: Always call `algolia_search_list_indices` before other tools to resolve `applicationId` and `indexName`. The `applicationId` parameter is an enum — select from the values in the tool schema, never guess.
2. **Index names are case-sensitive**: Use the exact name returned by `algolia_search_list_indices`.
3. **Date parameters**: Analytics tools accept `startDate` and `endDate` in `YYYY-MM-DD` format. Default period is the last 8 days.
4. **Permissions**: Not all tools are available to every user. Analytics tools require the Analytics permission; recommendations require the Recommend feature.

## Common Workflows

### Search Quality Audit
1. `algolia_search_list_indices` → get applicationId and index name
2. `algolia_analytics_no_results_rate` → check overall health (< 5% is excellent)
3. `algolia_analytics_searches_no_results` → find the specific failing queries
4. `algolia_analytics_top_searches` with `clickAnalytics: true` → find high-volume queries with low CTR
5. `algolia_analytics_click_positions` → check if clicks are concentrated at position 1 (good) or spread evenly (poor relevance)
6. For each problematic query: `algolia_search_index` with that query to see what results look like

### Recommendation Setup Check
1. `algolia_search_list_indices` → resolve applicationId
2. Start with `trending-items` (requires least data) to verify Recommend is working
3. Then try `bought-together` or `related-products` with a known product objectID
4. If results are empty, check event volume requirements in [recommendations reference](references/recommendations.md)

## Reference Docs

- [connection-setup](references/connection-setup.md) — MCP server configuration and authentication
- [search](references/search.md) — Search parameters, filter syntax (`facetFilters`, `numericFilters`), pagination
- [analytics](references/analytics.md) — Analytics metrics interpretation, date ranges, click/conversion tracking
- [recommendations](references/recommendations.md) — Recommendation models, thresholds, facet-based filtering
- [troubleshooting](references/troubleshooting.md) — Common errors and resolution steps

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [algolia](https://github.com/algolia)
- **Source:** [algolia/skills](https://github.com/algolia/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-algolia-skills-algolia-mcp
- Seller: https://agentstack.voostack.com/s/algolia
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.