App Market Intelligence MCP

google-play-list

Retrieve apps from Google Play collections to analyze market trends, research competitors, and understand user preferences across categories.

Instructions

Get apps from Google Play collections. Returns a list of apps with:

url: Play Store URL
appId: Package name (e.g., 'com.company.app')
title: App name
summary: Short description
developer: Developer name
developerId: Developer ID
icon: Icon URL
score: Rating (0-5)
scoreText: Rating display text
priceText: Price display text
free: Boolean indicating if app is free

When fullDetail is true, includes all fields from app details endpoint.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "google-play-list"
  }
}

Input Schema

Name	Required	Description	Default
`collection`	No	Collection to fetch apps from (default: TOP_FREE). Available collections: - TOP_FREE: Top free applications - TOP_PAID: Top paid applications - GROSSING: Top grossing applications	TOP_FREE
`category`	No	Category to filter by. Available categories: Main Categories: - APPLICATION: All applications - ANDROID_WEAR: Wear OS apps - ART_AND_DESIGN: Art & Design - AUTO_AND_VEHICLES: Auto & Vehicles - BEAUTY: Beauty - BOOKS_AND_REFERENCE: Books & Reference - BUSINESS: Business - COMICS: Comics - COMMUNICATION: Communication - DATING: Dating - EDUCATION: Education - ENTERTAINMENT: Entertainment - EVENTS: Events - FINANCE: Finance - FOOD_AND_DRINK: Food & Drink - HEALTH_AND_FITNESS: Health & Fitness - HOUSE_AND_HOME: House & Home - LIFESTYLE: Lifestyle - MAPS_AND_NAVIGATION: Maps & Navigation - MEDICAL: Medical - MUSIC_AND_AUDIO: Music & Audio - NEWS_AND_MAGAZINES: News & Magazines - PARENTING: Parenting - PERSONALIZATION: Personalization - PHOTOGRAPHY: Photography - PRODUCTIVITY: Productivity - SHOPPING: Shopping - SOCIAL: Social - SPORTS: Sports - TOOLS: Tools - TRAVEL_AND_LOCAL: Travel & Local - VIDEO_PLAYERS: Video Players - WATCH_FACE: Watch Faces - WEATHER: Weather Game Categories: - GAME: All Games - GAME_ACTION: Action Games - GAME_ADVENTURE: Adventure Games - GAME_ARCADE: Arcade Games - GAME_BOARD: Board Games - GAME_CARD: Card Games - GAME_CASINO: Casino Games - GAME_CASUAL: Casual Games - GAME_EDUCATIONAL: Educational Games - GAME_MUSIC: Music Games - GAME_PUZZLE: Puzzle Games - GAME_RACING: Racing Games - GAME_ROLE_PLAYING: Role Playing Games - GAME_SIMULATION: Simulation Games - GAME_SPORTS: Sports Games - GAME_STRATEGY: Strategy Games - GAME_TRIVIA: Trivia Games - GAME_WORD: Word Games - FAMILY: Family Games
`age`	No	Age range filter (only for FAMILY category). Options: FIVE_UNDER, SIX_EIGHT, NINE_UP
`num`	No	Number of apps to retrieve (default: 500)
`lang`	No	Language code for result text (default: en)	en
`country`	No	Country code to get results from (default: us)	us
`fullDetail`	No	Include full app details in results (default: false)

Implementation Reference

src/server.js:813-825 (handler)
The handler function that implements the core logic of the 'google-play-list' tool. It destructures the input parameters and calls gplay.list from the google-play-scraper library to fetch the list of apps from the specified Google Play collection, category, etc., then returns the results as a JSON string in the MCP response format.
```
  async ({ collection, category, age, num, lang, country, fullDetail }) => {
    const results = await gplay.list({
      collection,
      category,
      age,
      num,
      lang,
      country,
      fullDetail
    });
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  }
);
```

src/server.js:675-812 (schema)

Zod schema defining the input parameters and validation for the 'google-play-list' tool, including collection, category, age, num, lang, country, and fullDetail with defaults and detailed descriptions.

{
  collection: z.enum(['TOP_FREE', 'TOP_PAID', 'GROSSING', 'TOP_FREE_GAMES', 'TOP_PAID_GAMES', 'TOP_GROSSING_GAMES'])
    .default('TOP_FREE')
    .describe(
      "Collection to fetch apps from (default: TOP_FREE). Available collections:\n" +
      "- TOP_FREE: Top free applications\n" +
      "- TOP_PAID: Top paid applications\n" +
      "- GROSSING: Top grossing applications"
    ),
  category: z.enum([
    'APPLICATION',
    'ANDROID_WEAR',
    'ART_AND_DESIGN',
    'AUTO_AND_VEHICLES',
    'BEAUTY',
    'BOOKS_AND_REFERENCE',
    'BUSINESS',
    'COMICS',
    'COMMUNICATION',
    'DATING',
    'EDUCATION',
    'ENTERTAINMENT',
    'EVENTS',
    'FINANCE',
    'FOOD_AND_DRINK',
    'HEALTH_AND_FITNESS',
    'HOUSE_AND_HOME',
    'LIBRARIES_AND_DEMO',
    'LIFESTYLE',
    'MAPS_AND_NAVIGATION',
    'MEDICAL',
    'MUSIC_AND_AUDIO',
    'NEWS_AND_MAGAZINES',
    'PARENTING',
    'PERSONALIZATION',
    'PHOTOGRAPHY',
    'PRODUCTIVITY',
    'SHOPPING',
    'SOCIAL',
    'SPORTS',
    'TOOLS',
    'TRAVEL_AND_LOCAL',
    'VIDEO_PLAYERS',
    'WATCH_FACE',
    'WEATHER',
    'GAME',
    'GAME_ACTION',
    'GAME_ADVENTURE',
    'GAME_ARCADE',
    'GAME_BOARD',
    'GAME_CARD',
    'GAME_CASINO',
    'GAME_CASUAL',
    'GAME_EDUCATIONAL',
    'GAME_MUSIC',
    'GAME_PUZZLE',
    'GAME_RACING',
    'GAME_ROLE_PLAYING',
    'GAME_SIMULATION',
    'GAME_SPORTS',
    'GAME_STRATEGY',
    'GAME_TRIVIA',
    'GAME_WORD',
    'FAMILY'
  ]).optional().describe(
    "Category to filter by. Available categories:\n" +
    "Main Categories:\n" +
    "- APPLICATION: All applications\n" +
    "- ANDROID_WEAR: Wear OS apps\n" +
    "- ART_AND_DESIGN: Art & Design\n" +
    "- AUTO_AND_VEHICLES: Auto & Vehicles\n" +
    "- BEAUTY: Beauty\n" +
    "- BOOKS_AND_REFERENCE: Books & Reference\n" +
    "- BUSINESS: Business\n" +
    "- COMICS: Comics\n" +
    "- COMMUNICATION: Communication\n" +
    "- DATING: Dating\n" +
    "- EDUCATION: Education\n" +
    "- ENTERTAINMENT: Entertainment\n" +
    "- EVENTS: Events\n" +
    "- FINANCE: Finance\n" +
    "- FOOD_AND_DRINK: Food & Drink\n" +
    "- HEALTH_AND_FITNESS: Health & Fitness\n" +
    "- HOUSE_AND_HOME: House & Home\n" +
    "- LIFESTYLE: Lifestyle\n" +
    "- MAPS_AND_NAVIGATION: Maps & Navigation\n" +
    "- MEDICAL: Medical\n" +
    "- MUSIC_AND_AUDIO: Music & Audio\n" +
    "- NEWS_AND_MAGAZINES: News & Magazines\n" +
    "- PARENTING: Parenting\n" +
    "- PERSONALIZATION: Personalization\n" +
    "- PHOTOGRAPHY: Photography\n" +
    "- PRODUCTIVITY: Productivity\n" +
    "- SHOPPING: Shopping\n" +
    "- SOCIAL: Social\n" +
    "- SPORTS: Sports\n" +
    "- TOOLS: Tools\n" +
    "- TRAVEL_AND_LOCAL: Travel & Local\n" +
    "- VIDEO_PLAYERS: Video Players\n" +
    "- WATCH_FACE: Watch Faces\n" +
    "- WEATHER: Weather\n\n" +
    "Game Categories:\n" +
    "- GAME: All Games\n" +
    "- GAME_ACTION: Action Games\n" +
    "- GAME_ADVENTURE: Adventure Games\n" +
    "- GAME_ARCADE: Arcade Games\n" +
    "- GAME_BOARD: Board Games\n" +
    "- GAME_CARD: Card Games\n" +
    "- GAME_CASINO: Casino Games\n" +
    "- GAME_CASUAL: Casual Games\n" +
    "- GAME_EDUCATIONAL: Educational Games\n" +
    "- GAME_MUSIC: Music Games\n" +
    "- GAME_PUZZLE: Puzzle Games\n" +
    "- GAME_RACING: Racing Games\n" +
    "- GAME_ROLE_PLAYING: Role Playing Games\n" +
    "- GAME_SIMULATION: Simulation Games\n" +
    "- GAME_SPORTS: Sports Games\n" +
    "- GAME_STRATEGY: Strategy Games\n" +
    "- GAME_TRIVIA: Trivia Games\n" +
    "- GAME_WORD: Word Games\n" +
    "- FAMILY: Family Games"
  ),
  age: z.enum(['FIVE_UNDER', 'SIX_EIGHT', 'NINE_UP'])
    .optional()
    .describe("Age range filter (only for FAMILY category). Options: FIVE_UNDER, SIX_EIGHT, NINE_UP"),
  num: z.number()
    .default(500)
    .describe("Number of apps to retrieve (default: 500)"),
  lang: z.string()
    .default("en")
    .describe("Language code for result text (default: en)"),
  country: z.string()
    .default("us")
    .describe("Country code to get results from (default: us)"),
  fullDetail: z.boolean()
    .default(false)
    .describe("Include full app details in results (default: false)")
},

src/server.js:661-825 (registration)

The registration of the 'google-play-list' tool using server.tool(), including the tool name, description string, Zod schema, and handler function.

server.tool("google-play-list", 
  "Get apps from Google Play collections. Returns a list of apps with:\n" +
  "- url: Play Store URL\n" +
  "- appId: Package name (e.g., 'com.company.app')\n" +
  "- title: App name\n" +
  "- summary: Short description\n" +
  "- developer: Developer name\n" +
  "- developerId: Developer ID\n" +
  "- icon: Icon URL\n" +
  "- score: Rating (0-5)\n" +
  "- scoreText: Rating display text\n" +
  "- priceText: Price display text\n" +
  "- free: Boolean indicating if app is free\n\n" +
  "When fullDetail is true, includes all fields from app details endpoint.",
  {
    collection: z.enum(['TOP_FREE', 'TOP_PAID', 'GROSSING', 'TOP_FREE_GAMES', 'TOP_PAID_GAMES', 'TOP_GROSSING_GAMES'])
      .default('TOP_FREE')
      .describe(
        "Collection to fetch apps from (default: TOP_FREE). Available collections:\n" +
        "- TOP_FREE: Top free applications\n" +
        "- TOP_PAID: Top paid applications\n" +
        "- GROSSING: Top grossing applications"
      ),
    category: z.enum([
      'APPLICATION',
      'ANDROID_WEAR',
      'ART_AND_DESIGN',
      'AUTO_AND_VEHICLES',
      'BEAUTY',
      'BOOKS_AND_REFERENCE',
      'BUSINESS',
      'COMICS',
      'COMMUNICATION',
      'DATING',
      'EDUCATION',
      'ENTERTAINMENT',
      'EVENTS',
      'FINANCE',
      'FOOD_AND_DRINK',
      'HEALTH_AND_FITNESS',
      'HOUSE_AND_HOME',
      'LIBRARIES_AND_DEMO',
      'LIFESTYLE',
      'MAPS_AND_NAVIGATION',
      'MEDICAL',
      'MUSIC_AND_AUDIO',
      'NEWS_AND_MAGAZINES',
      'PARENTING',
      'PERSONALIZATION',
      'PHOTOGRAPHY',
      'PRODUCTIVITY',
      'SHOPPING',
      'SOCIAL',
      'SPORTS',
      'TOOLS',
      'TRAVEL_AND_LOCAL',
      'VIDEO_PLAYERS',
      'WATCH_FACE',
      'WEATHER',
      'GAME',
      'GAME_ACTION',
      'GAME_ADVENTURE',
      'GAME_ARCADE',
      'GAME_BOARD',
      'GAME_CARD',
      'GAME_CASINO',
      'GAME_CASUAL',
      'GAME_EDUCATIONAL',
      'GAME_MUSIC',
      'GAME_PUZZLE',
      'GAME_RACING',
      'GAME_ROLE_PLAYING',
      'GAME_SIMULATION',
      'GAME_SPORTS',
      'GAME_STRATEGY',
      'GAME_TRIVIA',
      'GAME_WORD',
      'FAMILY'
    ]).optional().describe(
      "Category to filter by. Available categories:\n" +
      "Main Categories:\n" +
      "- APPLICATION: All applications\n" +
      "- ANDROID_WEAR: Wear OS apps\n" +
      "- ART_AND_DESIGN: Art & Design\n" +
      "- AUTO_AND_VEHICLES: Auto & Vehicles\n" +
      "- BEAUTY: Beauty\n" +
      "- BOOKS_AND_REFERENCE: Books & Reference\n" +
      "- BUSINESS: Business\n" +
      "- COMICS: Comics\n" +
      "- COMMUNICATION: Communication\n" +
      "- DATING: Dating\n" +
      "- EDUCATION: Education\n" +
      "- ENTERTAINMENT: Entertainment\n" +
      "- EVENTS: Events\n" +
      "- FINANCE: Finance\n" +
      "- FOOD_AND_DRINK: Food & Drink\n" +
      "- HEALTH_AND_FITNESS: Health & Fitness\n" +
      "- HOUSE_AND_HOME: House & Home\n" +
      "- LIFESTYLE: Lifestyle\n" +
      "- MAPS_AND_NAVIGATION: Maps & Navigation\n" +
      "- MEDICAL: Medical\n" +
      "- MUSIC_AND_AUDIO: Music & Audio\n" +
      "- NEWS_AND_MAGAZINES: News & Magazines\n" +
      "- PARENTING: Parenting\n" +
      "- PERSONALIZATION: Personalization\n" +
      "- PHOTOGRAPHY: Photography\n" +
      "- PRODUCTIVITY: Productivity\n" +
      "- SHOPPING: Shopping\n" +
      "- SOCIAL: Social\n" +
      "- SPORTS: Sports\n" +
      "- TOOLS: Tools\n" +
      "- TRAVEL_AND_LOCAL: Travel & Local\n" +
      "- VIDEO_PLAYERS: Video Players\n" +
      "- WATCH_FACE: Watch Faces\n" +
      "- WEATHER: Weather\n\n" +
      "Game Categories:\n" +
      "- GAME: All Games\n" +
      "- GAME_ACTION: Action Games\n" +
      "- GAME_ADVENTURE: Adventure Games\n" +
      "- GAME_ARCADE: Arcade Games\n" +
      "- GAME_BOARD: Board Games\n" +
      "- GAME_CARD: Card Games\n" +
      "- GAME_CASINO: Casino Games\n" +
      "- GAME_CASUAL: Casual Games\n" +
      "- GAME_EDUCATIONAL: Educational Games\n" +
      "- GAME_MUSIC: Music Games\n" +
      "- GAME_PUZZLE: Puzzle Games\n" +
      "- GAME_RACING: Racing Games\n" +
      "- GAME_ROLE_PLAYING: Role Playing Games\n" +
      "- GAME_SIMULATION: Simulation Games\n" +
      "- GAME_SPORTS: Sports Games\n" +
      "- GAME_STRATEGY: Strategy Games\n" +
      "- GAME_TRIVIA: Trivia Games\n" +
      "- GAME_WORD: Word Games\n" +
      "- FAMILY: Family Games"
    ),
    age: z.enum(['FIVE_UNDER', 'SIX_EIGHT', 'NINE_UP'])
      .optional()
      .describe("Age range filter (only for FAMILY category). Options: FIVE_UNDER, SIX_EIGHT, NINE_UP"),
    num: z.number()
      .default(500)
      .describe("Number of apps to retrieve (default: 500)"),
    lang: z.string()
      .default("en")
      .describe("Language code for result text (default: en)"),
    country: z.string()
      .default("us")
      .describe("Country code to get results from (default: us)"),
    fullDetail: z.boolean()
      .default(false)
      .describe("Include full app details in results (default: false)")
  }, 
  async ({ collection, category, age, num, lang, country, fullDetail }) => {
    const results = await gplay.list({
      collection,
      category,
      age,
      num,
      lang,
      country,
      fullDetail
    });
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  }
);

src/server.js:30-30 (helper)
Import of the 'gplay' library used by the google-play-list handler to perform the actual Google Play app listing via gplay.list().
```
import gplay from '@jeromyfu/google-play-scraper';
```

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.0.0Jan 3, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
First observedAug 15, 2025

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the return format (list of apps with fields) and the effect of the fullDetail parameter, but lacks critical behavioral details such as rate limits, authentication needs, pagination behavior, error handling, or whether this is a read-only operation. For a tool with no annotations, this leaves significant gaps in understanding its operational characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the core purpose. It uses a bulleted list for return fields efficiently, and the second sentence adds important context about fullDetail. There is no wasted text, though it could be slightly more structured (e.g., separating purpose from return details more clearly).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (7 parameters, no annotations, no output schema), the description is moderately complete. It covers the purpose and return format, but lacks behavioral transparency (e.g., rate limits, auth) and does not explain output beyond field names. Without annotations or output schema, the description should do more to compensate, but it at least provides a clear overview of what the tool does and returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly with descriptions, defaults, and enums. The description adds minimal value beyond the schema by mentioning the effect of fullDetail (includes all fields from app details endpoint) and listing return fields, but does not provide additional semantic context for parameters like collection or category beyond what's in the schema. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get apps from Google Play collections' and specifies the resource (apps from collections). It distinguishes from siblings like google-play-details, google-play-search, and google-play-similar by focusing on collection-based listing rather than details, search, or similarity. The description is specific about what it returns (a list of apps with enumerated fields).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for fetching apps from collections (e.g., top free, top paid), but does not explicitly state when to use this tool versus alternatives like google-play-search (for query-based retrieval) or google-play-details (for individual app details). No explicit exclusions or prerequisites are mentioned, leaving usage context somewhat implied rather than clearly defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.