Connect Claude Code, Codex, Gemini CLI and other MCP clients to create and edit screenshot projects with AI, review them with browser tools, and export in the website editor.

Connect an AI tool

When MCP is enabled for this AppScreenshots deployment, connect a compatible AI tool to:

https://appscreenshots.net/api/mcp

Choose HTTP/Streamable HTTP and OAuth. Sign in with your AppScreenshots account in the browser, select the projects and assets the tool may use, and choose whether it can create projects. No database access or API key is required.

For an overview with example prompts, see the MCP landing page.

Connect your client

The commands below register the endpoint with each client. After connecting, complete the browser sign-in when the client presents it.

claude mcp add --transport http --scope user appscreenshots https://appscreenshots.net/api/mcp

Then run /mcp inside Claude Code and authorize. For a project-scoped connection, merge a .mcp.json file instead of registering user scope — do not configure both without intending a scope override.

codex mcp add appscreenshots --url https://appscreenshots.net/api/mcp
codex mcp login appscreenshots

Alternatively merge a [mcp_servers.appscreenshots] section with url = "..." into the client's config.toml.

gemini mcp add --transport http --scope user appscreenshots https://appscreenshots.net/api/mcp

Inside Gemini CLI, run /mcp auth appscreenshots. The settings-file variant uses httpUrl for Streamable HTTP with "oauth": {"enabled": true}.

Open /mcp-config, add an HTTP server with the endpoint, then use /mcp-config login appscreenshots. The config file is ~/.kimi-code/mcp.json:

{
  "mcpServers": {
    "appscreenshots": {
      "url": "https://appscreenshots.net/api/mcp"
    }
  }
}

Restart your session after adding configuration. Older kimi-cli distributions use kimi mcp add --transport http --auth oauth instead.

Merge the server into ~/.zcode/cli/config.json under mcp.servers, or add the HTTP service named appscreenshots in Settings → MCP:

{
  "mcp": {
    "servers": {
      "appscreenshots": {
        "type": "http",
        "url": "https://appscreenshots.net/api/mcp"
      }
    }
  }
}

Restart the session and complete the OAuth browser sign-in when the client presents it. Complete the sign-in promptly: the desktop client cancels a pending authorization after roughly 180 seconds.

Use your account or workspace's available custom MCP connection entry and select OAuth with the endpoint above. Availability depends on account and workspace controls — a public GitHub repository does not create a ChatGPT directory listing.

Client integration is documented from official client references and a completed protocol-level end-to-end test (OAuth, project creation, editing, website preview, export). Individual client certifications are pending; see the connection kit's verification matrix for current status.

Connection kit

The public appscreenshots-mcp repository ships ready-made config files for every client above, an optional agent Skill that teaches the screenshot workflow, and a doctor command that checks the server from your terminal:

git clone https://github.com/horace68/appscreenshots-mcp.git
node bin/appscreenshots.mjs config claude    # print a client config snippet
node bin/appscreenshots.mjs install-skill claude
node bin/appscreenshots.mjs doctor

The helper only prints configuration and installs the Skill. It is not a local stdio server — use your client's native remote connection.

Tools

The nine tools below are exposed over Streamable HTTP. Clients may prefix the names. The hosted server is the source of truth for input schemas and account permissions.

Tool	Kind	Purpose
`get_capabilities`	Read	Entitlements, design bounds (100–5000 px), devices, element types, `maxFrames` (20), `maxElementsPerFrame` (100), preview/export modes
`search_templates`	Read	Search public template metadata (`query`, `offset`)
`get_template`	Read	Read an entitled template by id
`list_projects`	Read	List authorized projects, 25 per page
`get_project`	Read	Read the current revision and editable design, with the `editorUrl`
`get_project_preview`	Read	Editor link, revision, frames and browser review instructions — text, not an image
`list_assets`	Read	List shared assets and assets in authorized projects, 50 per page
`create_project`	Write	Create from a template or blank canvas (`name`, optional `templateId`, `width`, `height`, `idempotencyKey`)
`update_project`	Write	Apply 1–100 structured operations per call with `expectedRevision` and `idempotencyKey`

Editing operations

update_project accepts a discriminated list of operations:

set_name — rename the project
add_frame / remove_frame / reorder_frames — manage frames
upsert_element — insert or replace an element; requires full geometry, preserves omitted fields for the same element type
patch_element — partial edit by element id; changing an element's type is not allowed
remove_element — delete an element
set_background — set one frame's background; shared backgrounds are materialized per frame
set_locales — set 1–20 locales and the default locale
set_canvas — canvas size (100–5000) and mode (separate or continuous)

Elements carry typography, device mockup fields, image assetId references, shapes, icons, rotation and stackOrder. Images are referenced by authorized assetId — never by URL or local path, and existing image references are retained server-side, so do not send them back.

Every logical write should use a fresh idempotency key; reuse it only for an identical retry. After a revision conflict, read the latest version and reconcile. Never use SQL, HTML or scripts as edit instructions.

Errors

Errors return a JSON {code, message} body with isError: true:

Code	Meaning
`REVISION_CONFLICT`	The project changed since `expectedRevision` — re-read and retry
`ASSET_NOT_AUTHORIZED`	The asset was not selected on the consent page
`FRAME_NOT_FOUND` / `ELEMENT_NOT_FOUND`	The referenced frame or element does not exist
`ELEMENT_TYPE_CHANGE_NOT_ALLOWED`	`patch_element` cannot change an element's type
`INVALID_FRAME_ORDER` / `INVALID_DEFAULT_LOCALE`	Malformed frame ordering or locale default
`DUPLICATE_ID`	An id collides with an existing one
`PROJECT_SIZE_LIMIT`	Frame, element or payload limit exceeded
`RATE_LIMITED`	Too many calls — HTTP 429 with `Retry-After`

Authorization and limits

The server uses OAuth 2.1 with PKCE and browser sign-in:

Scopes: projects:read, projects:write (only if you allow creating or editing), assets:read, and offline_access.
Access tokens and refresh tokens each last 30 days.
Access tokens require a live grant: if you revoke the connection, existing tokens stop working immediately.
Rate limits: 60 MCP calls per minute on the free plan, 120 per minute on paid plans. Exceeding the limit returns HTTP 429 with Retry-After: 60.
Request bodies are capped at 2 MB; projects are capped at 20 frames and 100 elements per frame.

Plan entitlements still apply: project, paid-template, custom-font and batch-export restrictions are unchanged, and there are no hosted AI charges — the connected AI supplies design and copy.

Start with your screenshots

Upload the original screenshots in the website editor. Authorize that project or select individual assets on the consent page. MCP does not expose binary upload tools; a file attached to a chat is not automatically accessible to this service.

Try this prompt:

Create an English App Store screenshot project from an available template using my authorized assets. Use short headlines and a clean layout. Open the editor using available browser tools, inspect screenshots and correct visual issues, then give me the project link for website export.

The connected AI supplies design and copy; MCP saves editable projects. get_project_preview returns the editor link and review instructions, not image bytes. An agent with browser tools can open the editor, inspect screenshots, correct the design through MCP and reload safely to review the latest version. Browser login is separate from MCP OAuth, and unsaved editor changes must be preserved before reload. The user previews and exports through the website editor.

Manage access

Open Settings → Connected AI tools to change selected projects/assets or revoke a connection. The tool cannot access unselected projects. If the website and an AI tool edit the same project at once, reload the latest project before saving conflicting changes.

Browser review does not require Browserless or a background rendering queue. This MCP exposes project tools and browser review guidance, not cloud rendering. Without browser/image tools, the agent should return the editor link and report visual review as pending, rather than claim verification.

Troubleshooting

Symptom	Fix
`invalid_redirect_uri: web clients require https redirect URIs`	Use a loopback redirect (`http://127.0.0.1:<port>/callback` or `http://localhost:<port>/callback`) and let loopback registrations default to a native client
401 with `WWW-Authenticate: Bearer resource_metadata=…`	Normal discovery response for unauthenticated calls — complete the OAuth flow in your client
Authorization expires repeatedly	Reconnect from the client; a revoked or expired grant invalidates refresh tokens
Client cancels the browser sign-in	Complete the sign-in promptly (some clients cancel after ~180 seconds) and restart the connection
429 `RATE_LIMITED` responses	Wait for `Retry-After` (60 s) before retrying; upgrade to a paid plan for 120 calls/min

For client-specific notes and the current verification matrix, see the connection kit troubleshooting guide.

Connect an AI tool

When MCP is enabled for this AppScreenshots deployment, connect a compatible AI tool to:

https://appscreenshots.net/api/mcp

For an overview with example prompts, see the MCP landing page.

Connect your client

The commands below register the endpoint with each client. After connecting, complete the browser sign-in when the client presents it.

claude mcp add --transport http --scope user appscreenshots https://appscreenshots.net/api/mcp

codex mcp add appscreenshots --url https://appscreenshots.net/api/mcp
codex mcp login appscreenshots

Alternatively merge a [mcp_servers.appscreenshots] section with url = "..." into the client's config.toml.

gemini mcp add --transport http --scope user appscreenshots https://appscreenshots.net/api/mcp

Inside Gemini CLI, run /mcp auth appscreenshots. The settings-file variant uses httpUrl for Streamable HTTP with "oauth": {"enabled": true}.

Open /mcp-config, add an HTTP server with the endpoint, then use /mcp-config login appscreenshots. The config file is ~/.kimi-code/mcp.json:

{
  "mcpServers": {
    "appscreenshots": {
      "url": "https://appscreenshots.net/api/mcp"
    }
  }
}

Restart your session after adding configuration. Older kimi-cli distributions use kimi mcp add --transport http --auth oauth instead.

Merge the server into ~/.zcode/cli/config.json under mcp.servers, or add the HTTP service named appscreenshots in Settings → MCP:

{
  "mcp": {
    "servers": {
      "appscreenshots": {
        "type": "http",
        "url": "https://appscreenshots.net/api/mcp"
      }
    }
  }
}

Restart the session and complete the OAuth browser sign-in when the client presents it. Complete the sign-in promptly: the desktop client cancels a pending authorization after roughly 180 seconds.

Connection kit

git clone https://github.com/horace68/appscreenshots-mcp.git
node bin/appscreenshots.mjs config claude    # print a client config snippet
node bin/appscreenshots.mjs install-skill claude
node bin/appscreenshots.mjs doctor

The helper only prints configuration and installs the Skill. It is not a local stdio server — use your client's native remote connection.

Tools

The nine tools below are exposed over Streamable HTTP. Clients may prefix the names. The hosted server is the source of truth for input schemas and account permissions.

Tool	Kind	Purpose
`get_capabilities`	Read	Entitlements, design bounds (100–5000 px), devices, element types, `maxFrames` (20), `maxElementsPerFrame` (100), preview/export modes
`search_templates`	Read	Search public template metadata (`query`, `offset`)
`get_template`	Read	Read an entitled template by id
`list_projects`	Read	List authorized projects, 25 per page
`get_project`	Read	Read the current revision and editable design, with the `editorUrl`
`get_project_preview`	Read	Editor link, revision, frames and browser review instructions — text, not an image
`list_assets`	Read	List shared assets and assets in authorized projects, 50 per page
`create_project`	Write	Create from a template or blank canvas (`name`, optional `templateId`, `width`, `height`, `idempotencyKey`)
`update_project`	Write	Apply 1–100 structured operations per call with `expectedRevision` and `idempotencyKey`

Editing operations

update_project accepts a discriminated list of operations:

set_name — rename the project
add_frame / remove_frame / reorder_frames — manage frames
upsert_element — insert or replace an element; requires full geometry, preserves omitted fields for the same element type
patch_element — partial edit by element id; changing an element's type is not allowed
remove_element — delete an element
set_background — set one frame's background; shared backgrounds are materialized per frame
set_locales — set 1–20 locales and the default locale
set_canvas — canvas size (100–5000) and mode (separate or continuous)

Errors

Errors return a JSON {code, message} body with isError: true:

Code	Meaning
`REVISION_CONFLICT`	The project changed since `expectedRevision` — re-read and retry
`ASSET_NOT_AUTHORIZED`	The asset was not selected on the consent page
`FRAME_NOT_FOUND` / `ELEMENT_NOT_FOUND`	The referenced frame or element does not exist
`ELEMENT_TYPE_CHANGE_NOT_ALLOWED`	`patch_element` cannot change an element's type
`INVALID_FRAME_ORDER` / `INVALID_DEFAULT_LOCALE`	Malformed frame ordering or locale default
`DUPLICATE_ID`	An id collides with an existing one
`PROJECT_SIZE_LIMIT`	Frame, element or payload limit exceeded
`RATE_LIMITED`	Too many calls — HTTP 429 with `Retry-After`

Authorization and limits

The server uses OAuth 2.1 with PKCE and browser sign-in:

Scopes: projects:read, projects:write (only if you allow creating or editing), assets:read, and offline_access.
Access tokens and refresh tokens each last 30 days.
Access tokens require a live grant: if you revoke the connection, existing tokens stop working immediately.
Rate limits: 60 MCP calls per minute on the free plan, 120 per minute on paid plans. Exceeding the limit returns HTTP 429 with Retry-After: 60.
Request bodies are capped at 2 MB; projects are capped at 20 frames and 100 elements per frame.

Plan entitlements still apply: project, paid-template, custom-font and batch-export restrictions are unchanged, and there are no hosted AI charges — the connected AI supplies design and copy.

Symptom	Fix
`invalid_redirect_uri: web clients require https redirect URIs`	Use a loopback redirect (`http://127.0.0.1:<port>/callback` or `http://localhost:<port>/callback`) and let loopback registrations default to a native client
401 with `WWW-Authenticate: Bearer resource_metadata=…`	Normal discovery response for unauthenticated calls — complete the OAuth flow in your client
Authorization expires repeatedly	Reconnect from the client; a revoked or expired grant invalidates refresh tokens
Client cancels the browser sign-in	Complete the sign-in promptly (some clients cancel after ~180 seconds) and restart the connection
429 `RATE_LIMITED` responses	Wait for `Retry-After` (60 s) before retrying; upgrade to a paid plan for 120 calls/min

For client-specific notes and the current verification matrix, see the connection kit troubleshooting guide.

Connect an AI tool

Connect an AI tool

Connect your client

Connection kit

Tools

Editing operations

Errors

Authorization and limits

Start with your screenshots

Manage access

Troubleshooting

Table of Contents

Connect an AI tool

Connect an AI tool

Connect your client

Connection kit

Tools

Editing operations

Errors

Authorization and limits

Start with your screenshots

Manage access

Troubleshooting

Table of Contents