mikusnuz/cws-mcp

npm version

한국어

MCP Badge

MCP server for Chrome Web Store extension management. Upload, publish, and manage Chrome extensions directly from Claude Code or any MCP client.

When to Use

Use this MCP when you need to:

• "Upload a new version of my Chrome extension" — build your ZIP and use the upload tool to push it as a draft
• "Publish my extension to the Chrome Web Store" — use publish to submit for review and go live
• "Check the review status of my extension" — use status to see review state, version, and deploy percentage
• "Update my extension's description or category" — use update-metadata to save and verify the draft listing
• "Cancel a pending submission" — use cancel to withdraw a submission under review
• "Set up staged rollout for my extension" — use publish with staged rollout, then deploy-percentage to ramp up

Tools

Tool	Description
upload	Upload a ZIP file to Chrome Web Store (update existing item draft)
publish	Submit/publish with publish type, rollout percentage, skip-review, and blockOnWarnings
status	Fetch the current status including review state, deploy percentage, and version
cancel	Cancel a pending submission
deploy-percentage	Set staged rollout percentage (0-100, must exceed current target)
get	Alias of status: v2 publication status, not listing text
get-metadata-ui	Read the current draft description, category, homepage URL, and support URL from the dashboard
update-metadata	Save those four supported draft fields through the dashboard and verify them after reload
update-metadata-ui	Alias of update-metadata

API Coverage

An upload returning IN_PROGRESS is pending: poll status until lastAsyncUploadState is SUCCEEDED before publishing. FAILED is a tool error. A blocked publish retains error.details, including the warnings that need attention.

This MCP server covers all Chrome Web Store API v2 endpoints:

v2 Endpoint	MCP Tool
media.upload	upload
publishers.items.publish	publish
publishers.items.fetchStatus	status
publishers.items.cancelSubmission	cancel
publishers.items.setPublishedDeployPercentage	deploy-percentage

All API requests use v2. The public API has no listing-text read/write endpoints; dashboard tools use Playwright and a separate signed-in Chrome profile. Saving listing fields never submits for review. Missing fields, unmatched categories, and unconfirmed saves return errors instead of success.

Setup

Requires Node.js 20 or newer, matching the Playwright runtime requirement.

1. Create OAuth2 Credentials

1. Go to Google Cloud Console
2. Create a project (or select existing)
3. Enable Chrome Web Store API
4. Create OAuth2 credentials (Desktop app type)
5. Note your Client ID and Client Secret

2. Get Refresh Token

Follow Google's OAuth flow for desktop apps using a local loopback redirect URI, PKCE, and the scope https://www.googleapis.com/auth/chromewebstore. Request offline access (access_type=offline; use prompt=consent when you need a new refresh token). Exchange the authorization code using the same redirect URI and keep the refresh token in your MCP client's secret/environment settings. The former copy-and-paste OOB redirect is no longer supported by Google.

3. Configure MCP

Add to your Claude Code MCP settings (~/.claude/settings.local.json):

{
  "mcpServers": {
    "cws-mcp": {
      "command": "node",
      "args": ["/path/to/cws-mcp/dist/index.js"],
      "env": {
        "CWS_CLIENT_ID": "xxxxx.apps.googleusercontent.com",
        "CWS_CLIENT_SECRET": "GOCSPX-xxxxx",
        "CWS_REFRESH_TOKEN": "1//xxxxx",
        "CWS_PUBLISHER_ID": "me",
        "CWS_ITEM_ID": "your-extension-id"
      }
    }
  }
}

Or install globally via npm:

{
  "mcpServers": {
    "cws-mcp": {
      "command": "npx",
      "args": ["-y", "cws-mcp"],
      "env": { ... }
    }
  }
}

Environment Variables

Variable	Required	Description
CWS_CLIENT_ID	Yes	Google OAuth2 Client ID
CWS_CLIENT_SECRET	Yes	Google OAuth2 Client Secret
CWS_REFRESH_TOKEN	Yes	OAuth2 Refresh Token
CWS_PUBLISHER_ID	No	Publisher ID (default: me)
CWS_ITEM_ID	No	Default extension item ID
CWS_DASHBOARD_PROFILE_DIR	No	Browser profile path for UI automation (default: ~/.cws-mcp-profile)

Usage Examples

Check extension status

Use the cws-mcp status tool

Upload and publish

1. Use cws-mcp upload with zipPath="/path/to/extension.zip"
2. Use cws-mcp publish

Hold publication until after approval

Use cws-mcp publish with:
- publishType="STAGED_PUBLISH"

Publish with skip-review

Use cws-mcp publish with skipReview=true

STAGED_PUBLISH holds an approved submission for a later publication; it is not the rollout percentage. Use deployPercentage separately for an eligible extension's gradual rollout.

Stop publishing on validation warnings

Use cws-mcp publish with blockOnWarnings=true

The default is false, matching the API. Inspect returned warningInfo.warnings even when publishing succeeds.

Read or save listing fields without submitting for review

Use cws-mcp get-metadata-ui with headless=false
Use cws-mcp update-metadata with:
- description="..."
- category="Developer Tools"
- homepageUrl="https://example.com"
- supportUrl="https://example.com/support"

Notes:

• category must match the visible option label exactly in the current dashboard language; English and Korean field labels are supported.
• These tools read/save the current dashboard draft, not the published listing or an arbitrary locale. Select the intended localization in the dashboard first; ambiguous fields fail safely.
• Change title, summary, and default locale in manifest.json / localized messages, rebuild, and upload the ZIP. Use the dashboard directly for icons and screenshots.
• First run with headless=false if login is required.
• Browser profile path defaults to ~/.cws-mcp-profile (override with CWS_DASHBOARD_PROFILE_DIR).
• Google Chrome must be installed. Dashboard UI changes can require selector updates; unverified saves return errors. Verify the dashboard before retrying an ambiguous failure.

Staged rollout

1. Use cws-mcp publish with deployPercentage=10
2. Monitor approval/publication with status
3. Use cws-mcp deploy-percentage with percentage=50
4. Use cws-mcp deploy-percentage with percentage=100

Note: deploy-percentage is only available for extensions with 10,000+ seven-day active users. The new percentage must always be higher than the current target.

Migrating from 1.x to 2.0

Google shuts down API v1 on October 15, 2026. Version 2.0 no longer calls it:

• get now returns v2 status. Its old projection argument is rejected; use get-metadata-ui for draft listing text. Published listing text is not exposed by v2.
• update-metadata now uses the same dashboard workflow as update-metadata-ui and therefore needs Chrome login, not just an API token.
• Raw metadata, title, summary, and defaultLocale inputs are rejected with guidance; unsupported inputs are never silently ignored.
• storeIconPath is no longer accepted as a working upload. The previous generic file-input approach could not verify which asset it changed; upload the icon in the Developer Dashboard instead.

License

MIT