Tools - Alura API

The MCP server at https://mcp.alura.io/mcp has tools in four groups. Each tool calls the REST operations listed with it, at the same prices. You don’t call tools yourself: you ask your assistant in plain words, and it picks the tool.

Products and shops

Search and open products and shops, reviews, tags, sales history and Etsy links.

Keywords and trends

Search volume, competition, related keywords, top results and what’s trending.

Saved research

Read, create and change saved folders and lists.

Usage and workspaces

API credits left, and switching between workspaces.

Behavior hints

Every tool tells the assistant what it may change, with the standard MCP hints. Assistants use them to decide when to ask you first: ChatGPT, for example, asks before any tool that isn’t read-only. Alura checks every call on its own side too, so a hint never grants access.

Hint	What it means for Alura’s tools
Read-only (`readOnlyHint`)	The tool changes nothing in Alura or on Etsy. Every research tool is read-only, and so are the tools that read saved research, usage and workspaces.
Destructive (`destructiveHint`)	The tool deletes or overwrites something your team relies on: `delete_saved`, `remove_from_saved_list`, `update_saved` (renames and moves) and `switch_workspace` (later calls act in another workspace). Assistants such as Claude ask before these.
Idempotent (`idempotentHint`)	Repeating the same call leaves things as the first call did. Every Alura tool that writes is idempotent: creating a list that already exists returns it, and adding an item twice adds it once.

The research tools are read-only while Alura serves only items it already has. When Alura starts fetching new items from Etsy on request, the seven tools that can start a fetch will be marked as not read-only, because a call can queue work in Alura. They still change nothing on Etsy. | Open world (openWorldHint) | The tool returns public data about Etsy shops and listings, which other people wrote. Categories, saved research, usage and workspace tools work on Alura’s own data only. | No tool changes anything on Etsy. Alura’s research is read-only; the only things the assistant can change are your saved folders, lists and items, and which workspace it works in.

Permissions

Each tool needs one permission, called a scope, that you allow on the approval screen when you connect. The assistant doesn’t see tools whose permission you left out.

Scope	On the approval screen	Tools
`research:read`	Search and read Etsy market research	Products and shops, keywords and trends, categories
`saved:read`	See saved research	`list_saved`, `get_saved_list_items`
`saved:write`	Save research for you	Creating, changing and deleting saved folders, lists and items
`usage:read`	See API credit usage	`get_usage`
None		`list_workspaces`, `switch_workspace`, shown only to people in more than one workspace

Arguments every tool takes

detail. detailed, the default, returns every field the tool shows. concise returns the key fields, for long lists or a quick check. The price is the same.
limit and cursor on list tools. Lists return 20 items by default and at most 50; reviews, shop products and related keywords at most 25. Pass a page’s next_cursor back as cursor for the next page.

Results come as structured data plus a short text copy. Reviews, titles, tags and shop announcements appear only in the structured data, never in the text the assistant reads as instructions.

Mature listings

Assistants see a little less than the REST API. Etsy’s API has no flag for mature listings, so Alura counts products in Etsy’s Sexual Wellness category, and every category under it, as mature. Over MCP, searches, trending, similar products, a shop’s products and reviews, keyword top results and the category browser leave them out, and so do shops whose active products are all mature. Asking for one by ID or Etsy link answers not_found, and in a saved list it shows as unavailable. The REST API with an API key returns them as before.

All tools

Products and shops

Tool	What it does	Cost	Behavior	Scope
`search_products`	Search Etsy products	10 API credits per page	Read-only	`research:read`
`get_products`	Get Etsy products	1 API credit per call, or 1 API credit per item returned	Read-only	`research:read`
`find_similar_products`	Find similar products	10 API credits per page	Read-only	`research:read`
`get_product_tags`	Get a product’s tags	1 API credit per page	Read-only	`research:read`
`lookup_etsy_url`	Look up an Etsy URL	1 API credit per call	Read-only	`research:read`
`search_shops`	Search Etsy shops	10 API credits per page	Read-only	`research:read`
`get_shop`	Get an Etsy shop	1 API credit per call	Read-only	`research:read`
`list_shop_products`	List a shop’s products	1 API credit per page	Read-only	`research:read`
`get_reviews`	Get reviews	1 API credit per page	Read-only	`research:read`
`get_sales_history`	Get sales history	1 API credit per call	Read-only	`research:read`
`browse_categories`	Browse Etsy categories	Free (0 API credits)	Read-only	`research:read`

Keywords and trends

Tool	What it does	Cost	Behavior	Scope
`get_keyword_metrics`	Get keyword metrics	1 API credit per item returned, or 1 API credit per call	Read-only	`research:read`
`get_related_keywords`	Get related keywords	1 API credit per page, or 1 API credit per item returned	Read-only	`research:read`
`get_keyword_top_results`	Get a keyword’s top products or shops	10 API credits per page, or 1 API credit per item returned	Read-only	`research:read`
`get_keyword_history`	Get keyword search history	1 API credit per call, or 1 API credit per item returned	Read-only	`research:read`
`get_trending`	Get trending on Etsy	10 API credits per page	Read-only	`research:read`

Saved research

Tool	What it does	Cost	Behavior	Scope
`list_saved`	List saved research	Free (0 API credits)	Read-only	`saved:read`
`get_saved_list_items`	Read a saved list	1 API credit per item returned	Read-only	`saved:read`
`create_saved_folder`	Create a saved folder	Free (0 API credits)	Writes data	`saved:write`
`create_saved_list`	Create a saved list	Free (0 API credits)	Writes data	`saved:write`
`update_saved`	Rename or move saved research	Free (0 API credits)	Destructive	`saved:write`
`add_to_saved_list`	Save to a list	Free (0 API credits)	Writes data	`saved:write`
`remove_from_saved_list`	Remove from a list	Free (0 API credits)	Destructive	`saved:write`
`delete_saved`	Delete a saved folder or list	Free (0 API credits)	Destructive	`saved:write`

Usage and workspaces

Tool	What it does	Cost	Behavior	Scope
`get_usage`	Get API usage	Free (0 API credits)	Read-only	`usage:read`
`list_workspaces`	List workspaces	Free (0 API credits)	Read-only	None
`switch_workspace`	Switch workspace	Free (0 API credits)	Destructive	None

Products and shops

Keywords and trends

Saved research

Usage and workspaces

​Behavior hints

​Permissions

​Arguments every tool takes

​Mature listings

​All tools

​Products and shops

​Keywords and trends

​Saved research

​Usage and workspaces

Behavior hints

Permissions

Arguments every tool takes

Mature listings

All tools

Products and shops

Keywords and trends

Saved research

Usage and workspaces