# StaticX MCP Server

[![npm](https://img.shields.io/npm/v/staticx-mcp-server)](https://www.npmjs.com/package/staticx-mcp-server)
[![license](https://img.shields.io/npm/l/staticx-mcp-server)](./LICENSE)

Official Model Context Protocol server for [StaticX](https://staticx.site), 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.

```json
{
  "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](https://staticx.site/documentation/mcp-clients).

## Claude Code

```bash
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

```bash
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

```bash
STATICX_API_TOKEN=sx_replace_with_your_token npx staticx-mcp-server http
```

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

```text
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

```text
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

```bash
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](./SECURITY.md). Do not open a public issue containing tokens, private URLs, or customer data.

## License

MIT