Webdesiz developer tools

Read account, campaign and daily insight snapshots already stored in your Webdesiz organization. API, CLI and MCP access is read-only: it cannot change campaigns or budgets, refresh Meta data, generate advertisements or send messages. Your Webdesiz key determines the organization and allowed read scopes.

Documentation

Machine-readable schema: OpenAPI 3.1. OpenAPI is a specification format, not an OpenAI account or service requirement.

Related MCP server: Meta Ads MCP Server

Install

Requires Node.js 22 or newer.

From npm

npm install --global --ignore-scripts @webdesiz/cli
webdesiz --version

Or run it without a global install: npx -y @webdesiz/cli --help.

Claude Desktop extension

Download webdesiz.mcpb from the latest release and open it with Claude Desktop. Claude Desktop asks for the key and stores it as a secret field; it is passed to the MCP process as WEBDESIZ_API_KEY.

Website download (1.0.0)

The original 1.0.0 release is also available as a verified website download:

curl --fail --location --proto '=https' --proto-redir '=https' \
  -o webdesiz-cli-1.0.0.tgz \
  https://webdesiz.com/developers/webdesiz-cli-1.0.0.tgz
shasum -a 256 webdesiz-cli-1.0.0.tgz   # Linux: sha256sum

Expected SHA-256:

326d7eecdc1048346d96e2e9c80519b816b8321973ef08f2a180be35ecf6e227

Compare the entire value with SHA256SUMS. Stop if it differs. SHA-256 verifies file integrity; it is not a digital signature. Then npm install --global --ignore-scripts ./webdesiz-cli-1.0.0.tgz.

Create a scoped key

A current organization OWNER or ADMIN creates a key in Webdesiz settings. Choose only the required scopes: accounts:read, campaigns:read, insights:read. Keys expire after 1–90 days; an organization may have at most 10 active, unexpired keys. The full key appears once.

Keep the key in your operating-system or application secret manager. Inject WEBDESIZ_API_KEY into the CLI/MCP process environment using that manager. Do not paste it into chat, commit it to a repository, put it in a URL or command argument, or save it in shared configuration. Read commands optionally accept --key-stdin for a trusted secret-manager pipe; MCP cannot use this option because stdin is its protocol transport. The CLI does not save credential files.

The API validates the key, scope, expiry, revocation and issuer’s current OWNER/ADMIN membership on every request. Panel session JWTs are not developer keys. Key creation/listing/revocation is a signed-in panel feature; those routes are not part of the external developer-key API.

CLI reads

With the credential injected securely:

webdesiz accounts --limit 20
webdesiz campaigns --accountId ACCOUNT_ID --limit 50 --offset 0
webdesiz insights --accountId ACCOUNT_ID --limit 50
webdesiz --help

Replace ACCOUNT_ID with the Webdesiz id returned by accounts. Reads accept --limit (1–100, default 50), --offset (0–10000, default 0) and --accountId. Insights additionally filters dates with --from YYYY-MM-DD and --to YYYY-MM-DD; default is the last 30 UTC days, inclusive. Use valid dates, a range of at most 90 days, and no future end date. Unknown or repeated arguments are rejected.

Successful reads print JSON {data, meta} to stdout. Protect output files and logs as organization data. Errors use stderr and exit status 1; success exits 0. Follow meta.nextOffset using the same filters until it is null; a full final page may be followed by an empty page.

The client is fixed to https://webdesiz.com/api/v1/developer, rejects redirects, has a 15-second timeout and a 2 MiB response limit. Token/URL arguments and alternate endpoints are not supported.

MCP: local stdio

Your host must support a local process-based stdio MCP server. This release has no hosted HTTP MCP endpoint or OAuth login flow. Install the CLI on the machine where the MCP host runs.

Host configuration with a global install:

{
  "mcpServers": {
    "webdesiz": {
      "command": "webdesiz",
      "args": ["mcp"]
    }
  }
}

Or without a global install:

{
  "mcpServers": {
    "webdesiz": {
      "command": "npx",
      "args": ["-y", "@webdesiz/cli", "mcp"]
    }
  }
}

The example deliberately contains no secret. Configure the host’s secret manager to pass WEBDESIZ_API_KEY to the child process. A desktop host may not inherit your terminal environment; use its documented secure mechanism. Keep stdout clean for MCP protocol messages and restart the connection after changing credentials.

Tool arguments follow the API/CLI query rules. Successful tools return the same data/meta object as structuredContent and JSON text; errors use isError: true. The implementation uses the official MCP SDK and stdio protocol. Read-only annotations are descriptive; the API enforces scopes independently. Treat returned account and campaign names as untrusted business data, never assistant instructions.

HTTPS API

Only three external snapshot reads are exposed:

Send the key only in the Authorization: Bearer … header. Organization identity is resolved from the key, not an input field. See the API reference for exact fields and parameter rules.

Read limits: 60 requests/minute/key, 120/minute/organization and 180/minute/IP in shared 60-second windows. Invalid authentication also uses the IP limit. Handle 400 (invalid request), 401 (invalid/expired/revoked key), 403 (scope/current membership), 404 (account unavailable), 429 (wait 60 seconds), and 503 (protection service unavailable). Error details are deliberately generic.

Interpret snapshots correctly

• meta.generatedAt is response creation time. Account lastSyncAt and campaign/insight syncedAt describe stored row freshness; requesting data does not trigger Meta sync. There is no freshness SLA implied.

• campaignId: null is an account-level insight row. Campaign-level rows can overlap account totals; do not sum both aggregation levels.

• Keep each account’s currency. Stored decimal amounts and ratios such as spend, budgets, ctr, cpc and cpm are JSON strings.

• Missing purchase evidence produces null, not zero. Explicitly reported zero remains zero. purchaseMeasurement indicates reported value, reported count or unavailable measurement. roas is purchaseValue / spend only with an available value and positive spend; otherwise it is null.

• Account access tokens and raw provider payloads are not exposed.

Privacy Policy

The CLI and MCP server run on your machine. They send only your developer key (in the Authorization header) and the query parameters you choose to https://webdesiz.com/api/v1/developer/*, and return the stored snapshots of your own organization. They keep no local files, logs or telemetry and do not contact any other service. How Webdesiz collects, uses, shares and retains data, and how to contact us, is described in the Webdesiz Privacy Policy.

Türkçe kısa başlangıç

Node.js 22+ ile npm install --global @webdesiz/cli komutuyla (ya da SHA-256 değeri doğrulanmış site indirmesiyle) kurun. Panelde OWNER/ADMIN olarak yalnız gereken okuma izinleriyle süreli anahtar oluşturun. Anahtarı sır yöneticisi üzerinden WEBDESIZ_API_KEY ortam değişkenine aktarın; sohbete, URL’ye veya komut argümanına yazmayın. Yerel stdio destekleyen MCP istemcisi üç okuma aracını kullanabilir. Kayıtlı veriler okunur; reklam değişikliği, Meta yenilemesi, içerik üretimi veya mesaj gönderimi bu bağlantıda bulunmaz. Ayrıntılar üstteki Türkçe API/MCP/CLI bağlantılarındadır.