ASO MCP Server

A Model Context Protocol (MCP) server for App Store Optimization (ASO) research in Google Play Store.

Please note: This MCP is a very early feature-limited prototype and is not yet ready for production use.

Built on top of google-play-scraper - a Python library for scraping Google Play Store data.

Features

App Search - Search for apps by keyword with price filtering
App Details - Get comprehensive information about any app
App Reviews - Fetch user reviews with sorting, filtering, and pagination
Collections & Categories - Browse top free, top paid, and grossing apps by category
Keywords Research - Get keyword suggestions from Google Play Store autocomplete
Metadata Validation - Validate titles, short descriptions, and full descriptions against Google Play limits
Country & Language Support - Access all Google Play supported countries and languages
Proxy Rotation - Optional proxy support with automatic rotation and retry on failure

Installation

Prerequisites

Python 3.14+
uv (recommended) or pip

Setup

# Clone the repository
git clone <repository-url>
cd aso-mcp-python

# Install dependencies with uv
uv sync

# Or with pip
pip install -e .

# Install development dependencies (for testing)
uv sync --dev
# Or with pip
pip install -e ".[dev]"

Usage

Running the Server

uv run python server.py

Integration with AI Assistants

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "aso": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "server.py"
      ],
      "cwd": "/path/to/aso-mcp-python"
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "aso": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "server.py"
      ],
      "cwd": "/path/to/aso-mcp-python"
    }
  }
}

Available Tools

App Search & Discovery

`google-play-search`

Search for apps in Google Play Store by keyword.

Parameters:

country (string) - Country code (e.g., us, de, jp)
language (string) - Language code (e.g., en, de, ja)
term (string) - Search term
num (integer, optional) - Number of results (default: 20)
price (string, optional) - Price filter: "all", "free", or "paid" (default: "all")

Returns: List of app overviews with basic info (title, developer, score, etc.)

`google-play-list`

Browse Google Play Store collections and categories.

Parameters:

country (string) - Country code
language (string) - Language code
collection (string) - Collection type: "TOP_FREE", "TOP_PAID", or "GROSSING"
category (string) - Category (e.g., "APPLICATION", "GAME_ACTION", "PRODUCTIVITY")
num (integer, optional) - Number of results (default: 50)
age (string, optional) - Age filter: "AGE_RANGE1" (5 and under), "AGE_RANGE2" (6-8), or "AGE_RANGE3" (9+)

Available Categories:

General: APPLICATION, GAME, FAMILY
App Categories: BUSINESS, EDUCATION, ENTERTAINMENT, FINANCE, HEALTH_AND_FITNESS, PRODUCTIVITY, TOOLS, and more
Game Categories: GAME_ACTION, GAME_ADVENTURE, GAME_PUZZLE, GAME_RACING, GAME_STRATEGY, and more

Returns: List of app overviews

`google-play-app`

Get comprehensive details about a specific app.

Parameters:

country (string) - Country code
language (string) - Language code
app_id (string) - App package ID (e.g., "com.spotify.music")

Returns: Detailed app information including:

Basic info (title, developer, summary, descriptions)
Ratings (score, reviews count, histogram)
Pricing (price, currency, in-app purchases)
Install statistics (installs, min/max installs)
Media (icon, screenshots, video, header image)
Technical details (version, Android version, release/update dates)
Contact info (email, website, address)
Legal (content rating, privacy policy)

`google-play-reviews`

Get user reviews for a specific app with pagination support.

Parameters:

country (string) - Country code
language (string) - Language code
app_id (string) - App package ID
sort (string, optional) - Sort order: "newest", "rating", or "helpfulness" (default: "newest")
num (integer, optional) - Number of reviews (default: 100)
filter_rating (integer, optional) - Filter by rating (1-5)
continuation_token (string, optional) - Token for fetching next page

Returns: Reviews with user info, rating, text, developer reply (if any), and pagination token for next page

Keywords Research

`google-play-suggest`

Get keyword suggestions for a given seed keyword.

Parameters:

country (string) - Country code (e.g., us, de, jp)
language (string) - Language code (e.g., en, de, ja)
keyword (string) - Seed keyword or partial keyword

Example:

country: "us"
language: "en"
keyword: "calc"

Returns: List of suggested keywords like ["calculator", "calculator app", "calculator free", ...]

Metadata Validation

`google-play-validate-title`

Validate a title against Google Play's 30 character limit.

Parameters:

title (string) - Title to validate

`google-play-validate-short-description`

Validate a short description against Google Play's 80 character limit.

Parameters:

short_description (string) - Short description to validate

`google-play-validate-full-description`

Validate a full description against Google Play's 4000 character limit.

Parameters:

full_description (string) - Full description to validate

Returns: Validation result with length, validity status, and any errors.

Reference Data

`get-google-play-languages`

Get all language codes supported by Google Play.

`get-google-play-countries`

Get all country codes supported by Google Play.

`get-google-play-countries-with-languages`

Get country codes mapped to their supported languages.

Proxy Configuration

The server supports optional proxy rotation for requests to Google Play. This is useful for:

Avoiding rate limiting
Geographic distribution of requests
IP rotation

Setup

Set the ASO_MCP_PROXIES environment variable with a comma-separated list of proxy URLs:

export ASO_MCP_PROXIES="http://proxy1:8080,http://proxy2:8080,http://user:pass@proxy3:8080"

With Claude Code

{
  "mcpServers": {
    "aso": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "server.py"
      ],
      "cwd": "/path/to/aso-mcp-python",
      "env": {
        "ASO_MCP_PROXIES": "http://proxy1:8080,http://proxy2:8080"
      }
    }
  }
}

With Gemini CLI

{
  "mcpServers": {
    "aso": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "server.py"
      ],
      "cwd": "/path/to/aso-mcp-python",
      "env": {
        "ASO_MCP_PROXIES": "http://proxy1:8080,http://proxy2:8080"
      }
    }
  }
}

How Proxy Rotation Works

On each request, a random proxy is selected from the pool
If a request fails, the proxy is marked as failed and a different proxy is tried
Failed proxies are avoided until all proxies have failed
When all proxies fail, the failed list resets and rotation starts over
Credentials in proxy URLs are masked in logs for security

Supported Proxy Formats

http://host:port
http://username:password@host:port
https://host:port
https://username:password@host:port

Google Play Metadata Limits

Field	Character Limit
Title	30
Short Description	80
Full Description	4000

Supported Countries

The server supports 60+ countries including:

Region	Countries
Americas	US, CA, BR, MX
Europe	GB, DE, FR, ES, IT, NL, PL, and more
Asia Pacific	JP, KR, CN, IN, AU, SG, and more
Middle East	SA, IL, TR, and more

Use get-google-play-countries-with-languages to get the full mapping of countries to their supported languages.

Development

Project Structure

aso-mcp-python/
├── server.py                 # Main MCP server
├── proxy.py                  # Proxy rotation manager
├── constants/
│   ├── google_play_constants.py  # Countries, languages, limits, enums
│   └── mcp_constants.py          # Server instructions
├── models/
│   ├── google_play.py        # Data models (AppDetails, AppOverview, Review)
│   └── metadata.py           # Validation models
├── tests/
│   └── test_server.py        # Comprehensive test suite
├── pyproject.toml            # Project configuration
├── pytest.ini                # Pytest configuration
└── README.md

Dependencies

mcp[cli] - Model Context Protocol SDK
play-store-scraper-ng - Google Play Store scraper
httpx - HTTP client

Development Dependencies

pytest - Testing framework
pytest-asyncio - Async test support
pytest-mock - Mocking support

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=. --cov-report=html

# Run specific test file
uv run pytest tests/test_server.py

# Run specific test
uv run pytest tests/test_server.py::TestSearch::test_google_play_search_success

# Run with verbose output
uv run pytest -v

The test suite includes:

Unit tests for all tools
Mock-based tests (no actual API calls)
Proxy rotation and failure scenarios
Input validation tests
Pagination tests for reviews

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
constants		constants
models		models
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
proxy.py		proxy.py
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
server.py		server.py
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

ASO MCP Server

Features

Installation

Prerequisites

Setup

Usage

Running the Server

Integration with AI Assistants

Claude Code

Gemini CLI

Available Tools

App Search & Discovery

google-play-search

google-play-list

google-play-app

google-play-reviews

Keywords Research

google-play-suggest

Metadata Validation

google-play-validate-title

google-play-validate-short-description

google-play-validate-full-description

Reference Data

get-google-play-languages

get-google-play-countries

get-google-play-countries-with-languages

Proxy Configuration

Setup

With Claude Code

With Gemini CLI

How Proxy Rotation Works

Supported Proxy Formats

Google Play Metadata Limits

Supported Countries

Development

Project Structure

Dependencies

Development Dependencies

Running Tests

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`google-play-search`

`google-play-list`

`google-play-app`

`google-play-reviews`

`google-play-suggest`

`google-play-validate-title`

`google-play-validate-short-description`

`google-play-validate-full-description`

`get-google-play-languages`

`get-google-play-countries`

`get-google-play-countries-with-languages`

Packages