@applistinglab/mcp
v0.1.1
Published
MCP server for the AppListingLab Developer API: App Store and Google Play screenshots, ASO text, localization and feature graphics from your AI agent
Maintainers
Readme
AppListingLab MCP server
Connect an AI agent to AppListingLab: create App Store and Google Play screenshots from real app captures, ASO listing text, localizations and Google Play feature graphics, and optionally publish to Google Play — through the released Developer API.
The server runs locally over stdio, started by your MCP host (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf and others) with your own Developer API key. There is no hosted MCP endpoint and nothing to deploy.
Requirements
- Node.js 22.19 or later on the host's
PATH. - A Developer API key from Studio → API keys.
- Optional: a folder for your captures and downloaded results. Upload and download tools appear only when it is configured.
Setup
Claude Code
claude mcp add applistinglab \
-e APP_LISTING_LAB_API_KEY=your_developer_api_key \
-e APP_LISTING_LAB_FILES_DIR=/absolute/path/to/store-assets \
-- npx -y @applistinglab/mcpClaude Desktop, Cursor, Windsurf and other mcpServers hosts
{
"mcpServers": {
"applistinglab": {
"command": "npx",
"args": ["-y", "@applistinglab/mcp"],
"env": {
"APP_LISTING_LAB_API_KEY": "your_developer_api_key",
"APP_LISTING_LAB_FILES_DIR": "/absolute/path/to/store-assets"
}
}
}
}Keep the key in the host's private configuration or secret environment. Never
commit it (for example in a shared project .mcp.json) or paste it into a chat
or tool argument; the server refuses tool calls that contain it.
Configuration
| Variable | Default | Purpose |
| --- | --- | --- |
| APP_LISTING_LAB_API_KEY | required | Your Developer API key. |
| APP_LISTING_LAB_FILES_DIR | unset | Existing folder for capture uploads, icon staging and downloads. |
| APP_LISTING_LAB_ENABLE_PUBLISHING | false | true adds the Google Play publishing tools. |
| APP_LISTING_LAB_STATE_DIR | ~/.applistinglab/mcp/<connection> | Private folder for retry manifests. |
| APP_LISTING_LAB_API_BASE | https://api.applistinglab.com/api/v1 | HTTPS /api/v1 base of the API. |
To keep the key out of the host's configuration, install the package
(npm install -g @applistinglab/mcp) and start it as
node --env-file=/absolute/private/applistinglab-mcp.env <global node_modules>/@applistinglab/mcp/dist/cli.js
with a chmod 600 env file. Launch node directly rather than through
npm start, which writes to stdout, the MCP protocol channel.
Tools
On startup the server reads the API's public stable
/developer/openapi.json and exposes the operations both released there and
on its reviewed allowlist. Preview, internal, admin and key-management routes
are never exposed. Restart the server after an API release to pick up new
operations.
| Workflow | Tools |
| --- | --- |
| Discovery | get_capabilities, list_screenshot_devices, list_screenshot_designs |
| App profile | list_apps, import_app, get_app |
| Real captures | list_source_screenshots, upload_source_screenshot |
| Screenshots | prepare_screenshots, suggest_screenshot_captions, generate_app_screenshots |
| Text and artwork | generate_aso_listing, localize_aso_listing, generate_feature_graphic |
| Results | get_job, wait_for_job, download_artifact |
| Google Play publishing (opt-in) | create_google_play_publish_session, stage_publish_artifact, stage_google_play_icon, start_google_play_publish, get_publish_session, get_google_play_listing, get_google_play_icon |
The applistinglab://capabilities resource reports the same settings and tool
list. Request bodies are nested under request, path identifiers use id and
locale queries use locale. Generation and publish-session creation also
require an idempotencyKey.
Files
Source uploads and icon staging take request.file, a file inside
APP_LISTING_LAB_FILES_DIR, instead of the API's request.dataUrl. Captures
may be PNG, JPEG or WebP up to 10 MiB; icons must be 512 × 512 PNGs up to
1 MiB. download_artifact saves a finished PNG under a new plain filename,
returns its dimensions, size and SHA-256, and never overwrites a file. Paths
that escape the folder, including through symlinks, are refused.
On the Free plan, downloaded screenshots carry a small "Made with
applistinglab.com" mark, as Studio's free exports do, and the result says
watermark: "free-plan". The stored artifact stays clean: after an upgrade the
same artifact downloads without the mark.
Retries and jobs
Give each intended generation a unique 20–200 character idempotencyKey. The
server saves the exact request to a private local manifest (0600, in a 0700
folder; API keys are never stored) before sending it, and rejects a changed
request under the same key. The API's own idempotency stays authoritative
across machines and keys. POSTs are never resent automatically: after a
timeout, call the tool again with the same arguments and key.
Generation returns a job. wait_for_job polls for up to 60 seconds and returns
the last state it read; pending and running are neither success nor
failure, and the deadline does not cancel the job. Download finished artifacts
by ID.
Refused requests return the HTTP status with the API's own code and
message, and retryAfterSeconds when the API sets it. Credits, scopes,
ownership, rate limits and plan eligibility are enforced by the API.
Google Play publishing
Set APP_LISTING_LAB_ENABLE_PUBLISHING=true and restart. The key must also
have the publish scope; enabling the tools never adds it. Publishing is a
separate, explicitly requested task: create the session with its review
policy, stage the complete ordered batch, start that same session once, then
read the result back. Provider commit, store approval and public release are
separate outcomes.
Links
License
MIT
