AppStore-MCP-Server

Pesquisa de otimização da App Store (ASO), metadados, rankings de palavras-chave e mais

Documentação

Servidor MCP da App Store

Um servidor MCP para pesquisar na App Store, verificar rankings de palavras-chave, analisar concorrência e acompanhar tendências — alimentado por um binário nativo do macOS para acesso rápido e direto às APIs da App Store.

Também funciona como uma ferramenta CLI independente com formatos de saída ricos.

Requisitos

macOS 26+ (Apple Silicon)

Início Rápido

Instalar via uvx (recomendado)

uvx appstore-mcp-server

Isso baixa o binário nativo na primeira execução e inicia o servidor MCP. Nenhuma instalação persistente é necessária.

Instalar via pip

pip install appstore-mcp-server
appstore-mcp-server

Baixar o binário diretamente

Baixe a versão mais recente do GitHub Releases, extraia e execute:

tar xzf appstore-*-macos-arm64.tar.gz
./appstore --mcp

Configuração do Cliente MCP

Claude Code

claude mcp add --scope user --transport stdio -- appstore-mcp-server uvx appstore-mcp-server

Ou com o binário diretamente:

claude mcp add --scope user --transport stdio -- appstore-mcp-server /path/to/appstore --mcp

Claude Desktop

Adicione à sua configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "appstore-mcp-server": {
      "command": "uvx",
      "args": ["appstore-mcp-server"]
    }
  }
}

Outros Clientes MCP

O servidor se comunica via stdio usando o protocolo MCP padrão. Execute com a flag --mcp:

/path/to/appstore --mcp

Ferramentas MCP

Ferramenta	Descrição
`search_apps`	API de Pesquisa do iTunes com filtros de atributo/gênero
`search_ranked`	API MZStore — resultados correspondem aos rankings reais da App Store
`lookup_app`	Buscar um aplicativo por ID, bundle ID ou URL da App Store
`top_charts`	Rankings atuais dos principais gráficos (gratuitos, pagos, mais lucrativos)
`find_app_rank`	Verificar onde um aplicativo está classificado para uma única palavra-chave
`check_app_rankings`	Verificar a classificação de um aplicativo em palavras-chave geradas automaticamente (lento)
`analyze_keyword`	Análise competitiva com pontuação de competitividade (0-100)
`app_competitors`	Encontrar os principais concorrentes de um aplicativo via resultados de pesquisa sobrepostos
`compare_keywords`	Comparar competitividade em múltiplas palavras-chave (lento)
`discover_trending`	Descobrir categorias em tendência a partir de novas entradas nos gráficos
`version`	Obter a versão do servidor

A maioria das ferramentas suporta:

storefront — Código de país de duas letras (padrão: US). Use para qualquer região da App Store.
verbosity — Controla o detalhe da resposta e o uso de tokens:
- compact (padrão) — Apenas campos principais, sem descrições. Melhor para a maioria das consultas.
- full — Inclui descrições de aplicativos e notas de versão.
- complete — Todos os campos da resposta da API. Verboso (~4KB/aplicativo).

Recursos MCP

Recurso	URI	Descrição
Storefronts	`appstore://storefronts`	Códigos de país e nomes para todas as regiões suportadas da App Store
Gêneros	`appstore://genres`	IDs e nomes de gêneros para categorias da App Store
Atributos de Pesquisa	`appstore://attributes`	Nomes de atributos de pesquisa disponíveis para buscas refinadas
Tipos de Gráficos	`appstore://chart-types`	Tipos de gráficos disponíveis para consultas de principais gráficos

Prompts MCP

Prompt	Descrição
`competitive_analysis`	Fluxo guiado: buscar um aplicativo, encontrar concorrentes, analisar rankings de palavras-chave e obter recomendações acionáveis. Argumentos: `keyword_or_app_id` (obrigatório), `storefront` (opcional).
`market_research`	Fluxo guiado: pesquisar rankings, principais gráficos, análise de competitividade, descoberta de tendências e identificação de oportunidades. Argumentos: `category` (obrigatório), `storefront` (opcional).

Uso da CLI

O binário também funciona como uma ferramenta CLI completa. Execute sem --mcp para uso interativo.

Comandos

Comando	Descrição
`search <query>`	Pesquisar na App Store (API de Pesquisa do iTunes)
`scrape <query>`	Pesquisar com resultados classificados correspondentes ao aplicativo da App Store (API MZStore)
`lookup <id-or-bundle>`	Buscar aplicativos por ID, bundle ID ou URL
`ranks <app-id>`	Analisar rankings de palavras-chave para um aplicativo
`analyze <query>`	Análise competitiva dos 20 principais resultados com correspondência de palavras-chave
`top <chart-type>`	Ver principais gráficos (gratuitos, pagos, mais lucrativos, novos gratuitos, novos pagos)
`list <type>`	Listar storefronts, gêneros, atributos ou tipos de gráficos

search

Pesquisar na App Store usando a API de Pesquisa do iTunes.

appstore search "photo editor"
appstore search --limit 5 minecraft
appstore search --storefront JP nintendo
appstore search --attribute softwareDeveloper "Meta Platforms"
appstore search --genre 6014 puzzle             # Games category
appstore search --verbosity minimal spotify
appstore search --output-format json spotify
appstore search --unlimited "weather"

Opções principais:

Opção	Descrição
`--limit <n>`	Número de resultados (1-200, padrão: 200, 0 para ilimitado)
`--unlimited`	Igual a `--limit 0`
`--attribute <attr>`	Pesquisar campo específico: `titleTerm`, `softwareDeveloper`, `descriptionTerm`
`--genre <id>`	Filtrar por ID de gênero (ex.: 6014 para Jogos)
`--storefront <code>`	Código do país (ex.: `US`, `JP`, `GB`)
`--output-format <fmt>`	`text` (padrão), `json`, `raw-json`, `markdown`, `html`, `html-open`
`--verbosity <level>`	`minimal`, `summary` (padrão), `expanded`, `verbose`, `complete`
`--full-description`	Mostrar descrições completas dos aplicativos

scrape

Pesquisar usando a API MZStore. Os resultados estão na ordem real de classificação da App Store — a mesma classificação que os usuários veem no aplicativo da App Store. Use isso em vez de search quando a posição no ranking for importante.

appstore scrape spotify
appstore scrape --limit 10 "photo editor"
appstore scrape --storefront GB twitter
appstore scrape --output-format json instagram

Opções principais:

Opção	Descrição
`--limit <n>`	Resultados máximos (padrão: 200)
`--storefront <code>`	Código do país (padrão: `US`)
`--output-format <fmt>`	`text` (padrão), `json`, `raw-json`, `markdown`, `html`
`--verbosity <level>`	`minimal`, `summary` (padrão), `expanded`, `verbose`, `complete`

lookup

Buscar aplicativos específicos por ID, bundle ID ou URL da App Store.

appstore lookup 284910350                                   # Numeric = app ID
appstore lookup com.spotify.client                          # Non-numeric = bundle ID
appstore lookup --ids 284910350,324684580                   # Multiple apps
appstore lookup --url "https://apps.apple.com/us/app/yelp/id284910350"
appstore lookup 284910350 --storefront JP
appstore lookup com.facebook.Facebook --output-format json

Opções principais:

Opção	Descrição
`--id <id>`	Buscar por ID do aplicativo
`--ids <id1,id2,...>`	Buscar múltiplos aplicativos (separados por vírgula)
`--bundle-id <bundle>`	Buscar por identificador de bundle
`--url <url>`	Buscar por URL da App Store
`--storefront <code>`	Código do país (padrão: `US`)
`--output-format <fmt>`	`text`, `json`, `raw-json`, `markdown`, `html`
`--verbosity <level>`	`minimal`, `summary` (padrão), `expanded`, `verbose`, `complete`

ranks

Analisar rankings de palavras-chave para um aplicativo. Gera automaticamente palavras-chave a partir do nome, subtítulo e descrição do aplicativo, depois verifica onde o aplicativo está classificado para cada palavra-chave. Usa IA no dispositivo (Apple Intelligence) para gerar palavras-chave adicionais quando disponível.

appstore ranks 324684580                        # Analyze Spotify's rankings
appstore ranks 284910350 --limit 30             # Test 30 keywords for Yelp
appstore ranks 544007664 --storefront GB        # UK store rankings

Opções principais:

Opção	Descrição
`--limit <n>`	Máximo de palavras-chave para testar (padrão: todas geradas)
`--storefront <code>`	Código do país (padrão: `US`)
`--verbosity <level>`	`minimal`, `summary` (padrão), `expanded`, `verbose`, `complete`

Este comando faz múltiplas chamadas sequenciais à API e pode levar de 30 a 120 segundos.

analyze

Analisar os 20 principais resultados de pesquisa para uma palavra-chave com métricas competitivas. Gera CSV com pontuações de correspondência, velocidade de avaliações, idade do aplicativo e um resumo de competitividade.

appstore analyze "cat toy"
appstore analyze --storefront GB "photo editor"
appstore analyze "music player" > results.csv

Colunas do CSV: ID do Aplicativo, Avaliação, Contagem de Avaliações, Lançamento Original, Último Lançamento, Dias de Idade, Dias de Atualização, Pontuação de Correspondência do Título, Pontuação de Correspondência da Descrição, Avaliações por Dia, Título, Gênero, Versão, iOS Mínimo, Classificação Etária.

Opções principais:

Opção	Descrição
`--storefront <code>`	Código do país (padrão: `US`)

top

Ver os principais gráficos da App Store.

appstore top free                               # Top free apps (US)
appstore top paid --limit 10                    # Top 10 paid apps
appstore top grossing --storefront JP           # Top grossing in Japan
appstore top paid --genre 6014                  # Top paid games
appstore top newfree --output-format json       # New free apps as JSON

Tipos de gráficos: free, paid, grossing, newfree, newpaid

Opções principais:

Opção	Descrição
`--limit <n>`	Número de resultados (1-200, padrão: 25)
`--genre <id>`	Filtrar por ID de gênero
`--storefront <code>`	Código do país (padrão: `US`)
`--output-format <fmt>`	`text`, `json`, `raw-json`, `markdown`, `html`
`--verbosity <level>`	`minimal`, `summary` (padrão), `expanded`, `verbose`, `complete`

list

Listar valores disponíveis para storefronts, gêneros, atributos ou tipos de gráficos.

appstore list storefronts                       # All country codes
appstore list genres                            # All genre IDs
appstore list attributes                        # Search attributes
appstore list charttypes                        # Chart types
appstore list storefronts --output-format json

Aliases: storefront/storefronts/country/countries, genre/genres/category/categories, attribute/attributes, charttype/charttypes/chart/charts.

Opções Comuns

Estas opções estão disponíveis na maioria dos comandos:

Opção	Descrição
`--storefront <code>`	País da App Store (`US`, `JP`, `GB`, `FR`, etc.)
`--country <code>`	Alias para `--storefront`
`--language <code>`	Idioma dos resultados (padrão: `en_us`)
`--output-format <fmt>`	Formato de saída (veja abaixo)
`--verbosity <level>`	Nível de detalhe (veja abaixo)
`--show-request`	Exibir detalhes da solicitação HTTP
`--show-response-headers`	Exibir cabeçalhos de resposta HTTP
`-o, --output-file <path>`	Escrever saída em arquivo
`-i, --input-file <path>`	Ler JSON em cache de arquivo
`--help, -h`	Mostrar ajuda para qualquer comando

Formatos de saída: text (padrão), json, raw-json, markdown, html, html-open (abre no navegador).

Níveis de verbosidade:

Nível	Descrição
`minimal`	Uma linha por aplicativo
`summary`	Detalhes principais (padrão)
`expanded`	Adiciona avaliações, tamanho, versão
`verbose`	Adiciona URLs, idiomas, recursos
`complete`	Todos os campos disponíveis

Compilando a partir do Código Fonte

git clone https://github.com/drewster99/appstore-mcp-server.git
cd appstore-mcp-server

Abra appstore.xcodeproj no Xcode e compile (Product > Build), ou:

xcodebuild build \
    -project appstore.xcodeproj \
    -scheme appstore \
    -configuration Release \
    -destination 'platform=macOS,arch=arm64'

O binário estará no diretório de produtos de build do DerivedData. Execute como servidor MCP com ./appstore --mcp ou como CLI com ./appstore <command>.

Arquitetura

O servidor usa duas APIs diferentes da Apple:

API MZStore — Retorna aplicativos na ordem real de classificação da App Store. Usada por search_ranked, find_app_rank, check_app_rankings, analyze_keyword, app_competitors, compare_keywords (e CLI scrape, ranks, analyze).
API de Pesquisa/Consulta do iTunes e RSS — Retorna metadados completos de aplicativos e dados de gráficos. Usada por search_apps, lookup_app, top_charts, discover_trending (e CLI search, lookup, top).

Para operações sensíveis a classificação, a API MZStore busca primeiro os IDs de aplicativos classificados, depois a API de Consulta do iTunes os enriquece com detalhes completos. Veja CLAUDE.md para detalhes de implementação.

Licença

MIT