// DOCS
AppHitlist MCP tools
Purpose, parameters and an example call for each tool on the AppHitlist MCP server.
AppHitlist registers these 9 MCP tools on POST /api/mcp. Each example is a JSON-RPC tools/call. Send the API key as a bearer token. Leave a parameter out to use its default. An argument that fails the schema comes back as the text "Internal error. Try again later." A JSON object with an error field is a named error, not a list of apps. The arguments below are values the input schema accepts. They are not sample results.
- MCP server — Server URL, call limits and client setup.
- API key — Create the bearer token these calls send.
find_chart_movers
Daily App Store chart movement: apps that climbed the most places and apps that entered the list since an earlier day. Pick the country (36 App Store countries), the list (grossing, free or paid), an optional category (for example fitness or Finance) and an optional date; days=1 compares with the day before, days=7 with a week earlier. Each riser shows its previous rank, new rank and change; each new entry shows its rank. Free keys get revenue and downloads as ranges (revenueRange, downloadsRange); subscribers get each app's monthly revenue and downloads as one figure instead (latestRevenueUsd, latestDownloads).
An unknown category returns error "category_not_found" and a categories array of the names to try again. A list that is not collected returns error "chart_not_available" with country, chart, category, date, latestChartDate and this hint: Daily lists cover 36 App Store countries. Overall lists exist for every kind in every country. Category lists: us, gb and de have grossing, free and paid; fr, ca, au, jp, kr, br, tr, es, it, mx, tw, nl, se, ch and sg have grossing and free; the other countries have grossing only. Raw daily lists are kept for 35 to 60 days. When there is no earlier chart, the warning is: No earlier chart to compare with yet, so there are no risers or new entries. Outside us, gb, de, the warning is: Only apps already in AppHitlist's catalog are recorded for this country, so an app that was added to the catalog recently can show up as a new entry.
Parameters
country— Optional. One of us, gb, de, fr, ca, au, jp, kr, br, tr, es, it, mx, tw, nl, se, ch, sg, hk, ae, sa, no, dk, pl, ru, in, id, th, nz, ie, at, be, za, il, cl, co. Default "us". Two-letter App Store country code, for example us, gb, de, jp, tr or brchart— Optional. One of grossing, free, paid. Default "grossing". Which daily list: grossing (top grossing, by revenue), free (top free) or paid (top paid)category— Optional. String, 1 to 60 characters. Optional category list, for example fitness or Finance. Leave it out for the overall list across all categories.date— Optional. String matching^\d{4}-\d{2}-\d{2}$. Chart day as YYYY-MM-DD (UTC). Leave it out for the latest day.days— Optional. Integer from 1 to 28. Default 1. Compare with the newest chart at least this many days earlier: 1 for day over day, 7 for week over weeklimit— Optional. Integer from 1 to 50. Default 20. Maximum risers and, separately, new entries to return
Example call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "find_chart_movers",
"arguments": {
"country": "us",
"chart": "grossing",
"category": "Finance",
"days": 7
}
}
}find_longest_running_ads
List active Meta (Facebook and Instagram) ads that have been running the longest, in one category (for example Food & Drink) or across all categories. Long-running ads usually mean the ad pays for itself. Subscriber only.
A key that is not a subscriber returns error "subscription_required" and upgradeUrl, the AppHitlist origin plus /#pricing. An unknown category returns error "category_not_found" and a categories array of the names to try again.
Parameters
category— Optional. String, 1 to 60 characters. App Store category: a name such as "Health & Fitness", "Finance" or "Food & Drink", a short name such as "fitness" or "puzzle games", or a numeric genre id. Valid names: Business, Weather, Utilities, Travel, Sports, Social Networking, Reference, Productivity, Photo & Video, News, Navigation, Music, Lifestyle, Health & Fitness, Games, Finance, Entertainment, Education, Books, Medical, Magazines & Newspapers, Food & Drink, Shopping, Developer Tools, Graphics & Design, Action, Adventure, Casual, Board, Card, Casino, Family, Puzzle, Racing, Role Playing, Simulation, Strategy, Trivia, Word.limit— Optional. Integer from 1 to 20. Default 10
Example call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "find_longest_running_ads",
"arguments": {
"category": "Food & Drink"
}
}
}find_new_winning_apps
List App Store apps released in the last 6 months that already earn $10K or more per month, highest first. Pass a category (for example fitness or Finance) to stay inside one category. Free keys get revenue and downloads as ranges (revenueRange, downloadsRange); subscribers get each app's monthly revenue and downloads as one figure instead (latestRevenueUsd, latestDownloads).
An unknown category returns error "category_not_found" and a categories array of the names to try again.
Parameters
category— Optional. String, 1 to 60 characters. App Store category: a name such as "Health & Fitness", "Finance" or "Food & Drink", a short name such as "fitness" or "puzzle games", or a numeric genre id. Valid names: Business, Weather, Utilities, Travel, Sports, Social Networking, Reference, Productivity, Photo & Video, News, Navigation, Music, Lifestyle, Health & Fitness, Games, Finance, Entertainment, Education, Books, Medical, Magazines & Newspapers, Food & Drink, Shopping, Developer Tools, Graphics & Design, Action, Adventure, Casual, Board, Card, Casino, Family, Puzzle, Racing, Role Playing, Simulation, Strategy, Trivia, Word.limit— Optional. Integer from 1 to 50. Default 20
Example call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "find_new_winning_apps",
"arguments": {
"category": "Finance"
}
}
}find_top_earning_apps
List the highest-earning App Store apps by monthly revenue, in one category (for example fitness or Finance) or across all categories. Use this for questions like 'what earns the most in Health & Fitness'. Free keys get revenue and downloads as ranges (revenueRange, downloadsRange); subscribers get each app's monthly revenue and downloads as one figure instead (latestRevenueUsd, latestDownloads), plus price and ratings.
An unknown category returns error "category_not_found" and a categories array of the names to try again.
Parameters
category— Optional. String, 1 to 60 characters. App Store category: a name such as "Health & Fitness", "Finance" or "Food & Drink", a short name such as "fitness" or "puzzle games", or a numeric genre id. Valid names: Business, Weather, Utilities, Travel, Sports, Social Networking, Reference, Productivity, Photo & Video, News, Navigation, Music, Lifestyle, Health & Fitness, Games, Finance, Entertainment, Education, Books, Medical, Magazines & Newspapers, Food & Drink, Shopping, Developer Tools, Graphics & Design, Action, Adventure, Casual, Board, Card, Casino, Family, Puzzle, Racing, Role Playing, Simulation, Strategy, Trivia, Word.limit— Optional. Integer from 1 to 50. Default 20
Example call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "find_top_earning_apps",
"arguments": {
"category": "fitness"
}
}
}get_app
Get one app by App Store URL, numeric id or name. Free keys get revenue and downloads as ranges (revenueRange, downloadsRange); subscribers get one monthly figure instead (latestRevenueUsd, latestDownloads), plus price, ratings and a 30-day chart rank summary.
An unknown app returns error "app_not_found". The app value in the example is the shape from this tool's input schema, not a live App Store id.
Parameters
app— Required. String, 1 to 200 characters. App Store URL (https://apps.apple.com/.../id123456789), numeric App Store id, or app name
Example call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_app",
"arguments": {
"app": "https://apps.apple.com/.../id123456789"
}
}
}get_app_ads
Active Meta (Facebook and Instagram) ads for the app, longest running first. Subscriber only.
A key that is not a subscriber returns error "subscription_required" and upgradeUrl, the AppHitlist origin plus /#pricing. An unknown app returns error "app_not_found". The app value in the example is the shape from this tool's input schema, not a live App Store id.
Parameters
app— Required. String, 1 to 200 characters. App Store URL (https://apps.apple.com/.../id123456789), numeric App Store id, or app namelimit— Optional. Integer from 1 to 20. Default 10
Example call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_app_ads",
"arguments": {
"app": "https://apps.apple.com/.../id123456789"
}
}
}get_app_complaints
Top complaint themes from the app's 1 and 2 star reviews. Subscriber only.
A key that is not a subscriber returns error "subscription_required" and upgradeUrl, the AppHitlist origin plus /#pricing. An unknown app returns error "app_not_found". The app value in the example is the shape from this tool's input schema, not a live App Store id.
Parameters
app— Required. String, 1 to 200 characters. App Store URL (https://apps.apple.com/.../id123456789), numeric App Store id, or app name
Example call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_app_complaints",
"arguments": {
"app": "https://apps.apple.com/.../id123456789"
}
}
}get_category_complaints
The most common complaint topics from 1 and 2 star reviews across all apps in one category (for example Finance). Each topic shows how many reviews and apps mention it, plus example apps. Optionally only product, billing or price complaints. Subscriber only.
A key that is not a subscriber returns error "subscription_required" and upgradeUrl, the AppHitlist origin plus /#pricing. An unknown category returns error "category_not_found" and a categories array of the names to try again.
Parameters
category— Required. String, 1 to 60 characters. App Store category: a name such as "Health & Fitness", "Finance" or "Food & Drink", a short name such as "fitness" or "puzzle games", or a numeric genre id. Valid names: Business, Weather, Utilities, Travel, Sports, Social Networking, Reference, Productivity, Photo & Video, News, Navigation, Music, Lifestyle, Health & Fitness, Games, Finance, Entertainment, Education, Books, Medical, Magazines & Newspapers, Food & Drink, Shopping, Developer Tools, Graphics & Design, Action, Adventure, Casual, Board, Card, Casino, Family, Puzzle, Racing, Role Playing, Simulation, Strategy, Trivia, Word.kind— Optional. One of product, billing, price. Only complaints about the product itself, about billing, or about pricelimit— Optional. Integer from 1 to 30. Default 15
Example call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_category_complaints",
"arguments": {
"category": "Finance",
"kind": "product"
}
}
}search_apps
Search App Store apps by app or developer name. Returns name, category, release date and revenue and downloads as ranges (revenueRange, downloadsRange); subscribers get one monthly figure instead (latestRevenueUsd, latestDownloads), plus price and ratings.
Parameters
query— Required. String, 2 to 80 characters. App or developer namelimit— Optional. Integer from 1 to 10. Default 5
Example call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_apps",
"arguments": {
"query": "Finance"
}
}
}