Staticx Mcp Server

npm license

Official Model Context Protocol server for StaticX, the deployment infrastructure for static websites.

Give Claude Code, Cursor, Codex, Cline, Windsurf, Claude Desktop, Zed, Continue, or another MCP client a scoped StaticX API token. The agent can then create sites, upload files, publish releases, inspect logs, start manual custom domain setup, and roll back with explicit confirmation when deployment history is enabled.

StaticX intentionally uses scoped API tokens instead of OAuth because it is designed for developers, CI/CD, automation tools, and AI agents.

Install

The package runs directly through npx; a global install is not required.

{
  "mcpServers": {
    "staticx": {
      "command": "npx",
      "args": ["-y", "staticx-mcp-server"],
      "env": {
        "STATICX_API_TOKEN": "sx_replace_with_your_token",
        "STATICX_API_BASE_URL": "https://staticx.site/api/v1"
      }
    }
  }
}

Create the narrowest token that fits the job. A short-lived, site-scoped token is the safest default for one-site deployments.

Full client-specific snippets are available in the StaticX MCP documentation.

Claude Code

claude mcp add staticx --scope user \
  --env STATICX_API_TOKEN=sx_replace_with_your_token \
  --env STATICX_API_BASE_URL=https://staticx.site/api/v1 \
  -- npx -y staticx-mcp-server

Codex

codex mcp add staticx \
  --env STATICX_API_TOKEN=sx_replace_with_your_token \
  --env STATICX_API_BASE_URL=https://staticx.site/api/v1 \
  -- npx -y staticx-mcp-server

Local HTTP debugging

STATICX_API_TOKEN=sx_replace_with_your_token npx staticx-mcp-server http

Then connect a Streamable HTTP client or the MCP Inspector to:

http://localhost:3100/mcp

HTTP mode listens on 127.0.0.1 by default. Do not expose it publicly without a secure reverse proxy and a deliberate authentication policy.

Environment variables

Variable	Required	Purpose
STATICX_API_TOKEN	Yes	Scoped StaticX API token.
STATICX_API_BASE_URL	No	Defaults to https://staticx.site/api/v1.
STATICX_PROJECT_ID	No	Default site ID for site-specific tools.
STATICX_TIMEOUT_MS	No	API request timeout in milliseconds.
STATICX_IMPORT_POLL_INTERVAL_MS	No	ZIP import poll interval, default 2000.
STATICX_IMPORT_POLL_TIMEOUT_MS	No	ZIP import wait timeout, default 15 minutes.
STATICX_DEPLOY_POLL_INTERVAL_MS	No	Deployment poll interval, default 5000.
STATICX_DEPLOY_POLL_TIMEOUT_MS	No	Deployment wait timeout, default 15 minutes.
STATICX_MCP_PORT	No	Local HTTP port, default 3100.
STATICX_MCP_HOST	No	Local HTTP bind host, default 127.0.0.1.

Never paste a real token into documentation, source control, screenshots, prompts, or issue reports.

Plan limits

MCP tools use the public StaticX API and cannot bypass account capacity.

Plan	Sites	Storage	Max upload	Form entries	Team seats	Rollback history
Free	1	500 MB	500 MB	1,000	1	Last 5 versions
Plus	15	10 GB	50 GB	20,000	5	Last 10 versions
Pro	100	20 GB	50 GB	100,000	10	Last 50 versions
Agency	Custom	Custom	50 GB	Custom	Custom	Custom

If a tool returns PLAN_QUOTA_EXCEEDED, stop and return the exact message to the user. Do not retry blindly, change endpoints, or bypass StaticX Forms.

Tools

Tool	Purpose
staticx_config	Show configuration state without exposing secrets.
staticx_auth_check	Validate the configured token.
staticx_list_workspaces	List accessible workspaces.
staticx_create_workspace	Create a workspace.
staticx_list_projects	List accessible sites.
staticx_get_project	Read one site.
staticx_create_project	Create a site. Optional versioning_enabled:false starts it in baseline-only mode.
staticx_upload_zip	Upload a static build ZIP and wait for queued import completion.
staticx_import_url	Import a public website URL.
staticx_deploy_project	Publish the current workspace.
staticx_deploy_zip	Upload a ZIP, wait for import completion, deploy, read state, and return the live URL.
staticx_list_deployments	List releases. Sites may use versioned history or one baseline release.
staticx_rollback_deployment	Roll back with exact confirmation text.
staticx_delete_deployment	Delete an inactive release with exact confirmation text.
staticx_get_logs	Read recent site activity.
staticx_connect_custom_domain	Start manual one-record custom domain setup.
staticx_get_custom_domain_status	Read domain activation status.
staticx_set_environment_variables	Sync site environment variables.
staticx_agent_guide	Return the built-in safe deployment guide.

Safety contract

• Tokens are never returned by a tool.
• Write tools explain their effect in their descriptions.
• Rollback requires ROLLBACK <deployment_id>.
• Deployment deletion requires DELETE <deployment_id>.
• The server only calls the public StaticX /api/v1 contract.
• Use a site-scoped token for one-site agents and revoke it when the task is complete.
• Plan limits are enforced by the API and hosted forms runtime. Tools must stop on PLAN_QUOTA_EXCEEDED.
• ZIP uploads are queued by the StaticX API. staticx_upload_zip and staticx_deploy_zip wait for import completion before reporting success or publishing.
• Sites default to versioned deployment history. If the user asks to avoid release history, pass versioning_enabled: false to staticx_create_project, staticx_deploy_project, or staticx_deploy_zip; StaticX keeps one baseline release for analytics, forms, and live serving.
• DNS Connect requires browser approval in the StaticX dashboard. MCP tools should return manual DNS records or tell the user to approve DNS Connect; they must not claim to authorize an external DNS provider silently.
• Generated subdomain suffix changes are dashboard-only. If an account has an active publishing domain, use Site → Settings → Domain to save a generated address on that suffix.

Recommended agent prompt

Use StaticX MCP to deploy this static website.

Before deploying:
- build the project
- verify index.html and 404.html exist at the build root
- explain what you will publish

After deploying:
- return the live URL, release, and deployment mode
- inspect logs if anything fails
- stop on PLAN_QUOTA_EXCEEDED and show the exact quota message
- if I ask to disable version history, create or deploy with versioning_enabled=false
- if the user asks to move a generated subdomain to a publishing domain, direct them to Site Settings → Domain
- do not roll back or delete anything without asking me first

Development

git clone https://github.com/madprodworks-coder/staticx-mcp-server.git
cd staticx-mcp-server
npm install
npm test

The MCP package must continue to use the public StaticX API. It must not import Laravel controllers, services, or internal engine classes.

Security

Please report vulnerabilities privately as described in SECURITY.md. Do not open a public issue containing tokens, private URLs, or customer data.

License

MIT