cloudarmor-mcp
A read-only MCP server for daily Google Cloud Armor WAF log patrol via Cloud Logging.
Get a one-call
daily_briefmorning summary of enforced DENYs, home-region false-positive candidates, and preview DENYs.Count enforced DENY events per Cloud Armor rule priority over a configurable window.
Identify enforced DENYs from your home region that may be false positives, excluding known-normal priorities.
Review preview/dry-run DENY counts to spot rules that may be ready to promote to enforce.
Run a
health_checkto verify version, configuration presence, and Cloud Logging API access.Adjust lookback windows with
since_hours(default 26 hours) on the reporting tools.Requires GCP project and service-account credentials;
home_region_deniesadditionally requiresCLOUDARMOR_HOME_REGION.
Provides tools to patrol Google Cloud Armor WAF logs, summarizing denied requests per rule, checking home-region false positives, and reviewing preview rules, with data from Cloud Logging.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cloudarmor-mcp Run the daily WAF brief"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cloudarmor-mcp
English | 日本語
MCP server for Google Cloud Armor WAF log patrol — deny summaries per rule, home-region false-positive checks, and preview (dry-run) rule review, straight from Cloud Logging.
Built for a daily "is the WAF healthy?" patrol: one daily_brief call answers what did we block, did we block anyone we shouldn't have, and are the preview rules ready to promote.
Documentation: https://shigechika.github.io/cloudarmor-mcp/
Tools
Tool | Purpose |
| One-call morning summary: enforced DENYs by rule priority, home-region false-positive lens, preview DENYs |
| Enforced DENY counts per rule priority |
| Enforced DENYs whose source IP geolocates to your home region — anything not marked known-normal is a false-positive candidate |
| Preview (dry-run) DENY counts — a quiet preview rule is a promotion candidate |
| Version, config presence, and a minimal Cloud Logging probe |
All tools are read-only. Counts are hard-capped (default 2000 entries per query) and a capped result is reported as >= N (capped), never as an exact total.
Related MCP server: gke-cred-audit
Setup
1. Least-privilege service account
Create a service account with roles/logging.viewer only and download a key. Unlike human accounts, service accounts are not subject to organization re-authentication policies, so an unattended patrol never silently expires.
gcloud iam service-accounts create waf-log-viewer --project=YOUR_PROJECT
gcloud projects add-iam-policy-binding YOUR_PROJECT \
--member=serviceAccount:waf-log-viewer@YOUR_PROJECT.iam.gserviceaccount.com \
--role=roles/logging.viewer
gcloud iam service-accounts keys create key.json \
--iam-account=waf-log-viewer@YOUR_PROJECT.iam.gserviceaccount.com2. Install
pip install cloudarmor-mcp
# or
uv tool install cloudarmor-mcp3. Environment variables
Variable | Required | Meaning |
| yes | GCP project ID that receives the load-balancer logs |
| yes | Path to the service-account key file |
| no | Comma-separated backend service names to filter (default: all) |
| no | ISO region code treated as home traffic, e.g. |
| no | Path to a rules INI (labels + known-normal priorities, see below) |
| no | Max entries fetched per query (default 2000) |
4. Optional rules INI
Keep your rule numbering out of prompts and give the reports human-readable labels:
[rules]
101 = block non-home deep-path crawlers
500 = AutoDiscover probe block
1002 = OWASP LFI protection
[home]
; home-region DENYs on these priorities are expected, not false positives
known_normal_priorities = 500, 6005. Claude Code (plugin)
This repository doubles as a single-plugin marketplace, so Claude Code can install the server for you:
/plugin marketplace add shigechika/cloudarmor-mcp
/plugin install cloudarmor-mcp@cloudarmor-mcpThe plugin launches uvx cloudarmor-mcp and reads the same environment variables
described in Environment variables above; export them
before starting Claude Code. GOOGLE_APPLICATION_CREDENTIALS still has to point at
a service-account key file that exists on your own machine — the plugin can't ship
or fetch that file for you, so this server can't be fully configured through the
plugin's own settings alone.
uvx must be on the PATH of the process that runs Claude Code — a login
shell usually has it, but a GUI-launched app may not; install
uv system-wide if the plugin fails to start.
6. Claude Code (manual)
claude mcp add cloudarmor -- cloudarmor-mcpwith the environment variables above in the server's env.
7. Codex
codex mcp add cloudarmor -- cloudarmor-mcpPass the environment variables above with --env KEY=VALUE (before --).
Any other MCP client that launches stdio servers works the same way: give it
cloudarmor-mcp as the command and set the environment variables above in its
environment.
CLI
cloudarmor-mcp --version # print version
cloudarmor-mcp --check # config + API probe (exit 0 when healthy)
cloudarmor-mcp --brief # print daily_brief to stdout (cron / smoke tests)Exporting one day of DENY entries (batch)
cloudarmor-mcp deny-export --date 2026-09-22 --tz Asia/Tokyo > out.tmp && mv out.tmp 2026-09-22.jsonWrites one JSON document to stdout with one record per DENY log entry of that
calendar day ([00:00, 24:00) in --tz, default UTC): the enforced and preview
policy verdicts (policy, priority, action, outcome, rule_ids), source IP,
region code and ASN as Cloud Armor logged them, method, host, path (query string
dropped — only its length is kept), status, User-Agent (200 chars) and backend.
--kind both (default) fetches entries where either policy says DENY in a single
query, so a request that matched a preview rule and was denied appears once with
both sections filled. --backend a,b overrides CLOUDARMOR_BACKEND_SERVICES.
This and traffic-export (below) are the only outputs of the package that contain per-request log data; it is
meant for an operator batch on the same host that aggregates the day itself. The
document ends with count, fetched, malformed and capped: when capped is
true the export stopped at --max-entries (default 200000; CLOUDARMOR_MAX_ENTRIES
does not apply) and is a prefix of the day, oldest first. Records are streamed, so
memory does not grow with the day, and pages are fetched at most one per 1.2 s to stay
under the Cloud Logging read quota (60 requests per minute), so a day with 200,000 entries
takes a few minutes. A day that has not ended yet is refused. Run it
some minutes after local midnight — Cloud Logging entries arrive with a delay — and
write to a temporary file first: on a query failure the exit code is 1 and stdout may
hold an unterminated document.
Exporting a sampled day of all requests (batch)
cloudarmor-mcp traffic-export --date 2026-09-22 --tz Asia/Tokyo --sample 0.01 > out.tmp && mv out.tmp 2026-09-22.jsonSame document layout and record fields as deny-export, but for every
load-balancer request of the day — allowed, denied and served from the CDN cache —
thinned by Cloud Logging's sample(insertId, RATE) (--sample, default 0.01).
The sample is a hash of each entry's insertId, so it is spread evenly over the day
and the same rate selects the same entries on every run; scale counts by
1 / sample to estimate the day — but not when capped is true: entries are read
oldest first, so a capped export covers only the early part of the day (lower
--sample or raise --max-entries instead). Each record adds cache_hit. When no
backend security policy evaluated a request (a CDN cache hit, for example) it has
enforced: null and no region code or ASN; use cache_hit, not enforced, to tell
cache hits apart.
The header carries sample instead of kind. Use it to see who visits — browsers,
crawlers, AI agents — which the DENY logs cannot show. The per-request caveats of
deny-export apply: the records include legitimate visitors' addresses.
Reading the report
Enforced DENY by rule — your normal blocking volume. Sudden shifts in the mix are worth a look.
Home-region DENY — requests from your own country/region that were blocked. Legitimate users and legitimate crawlers being denied show up here; scanner traffic that happens to originate locally will too, so the
known_normal_prioritieslist keeps expected rules (e.g. an AutoDiscover block) out of the suspicious list.Preview DENY — rules in dry-run. A preview rule that stays free of home-region hits over time is a candidate for promotion to enforce.
License
MIT
Available Tools
5 toolsdaily_briefB
Morning patrol summary: enforced DENYs by rule, home-region
false-positive check, and preview DENYs, in one call.
Inputs: since_hours. Returns: result
enforce_deniesD
Enforced DENY counts per Cloud Armor rule priority over the window.
Inputs: since_hours. Returns: result
health_checkA
Service health: version, config presence and a minimal API probe.
Returns a fixed shape (status/service/version + backend fields) so a monitoring caller never has to branch on missing keys. status is "healthy" when the config loads and a 1-entry probe query succeeds, "degraded" when config loads but the probe fails, "error" when the config itself is unusable.
Inputs: no named parameters.
home_region_deniesA
Enforced DENYs whose source IP geolocates to the home region.
This is the false-positive lens: home-region users being denied on a priority that is not marked known-normal deserves review. Requires CLOUDARMOR_HOME_REGION.
Inputs: since_hours. Returns: result
preview_deniesA
Preview (dry-run) DENY counts per rule priority over the window.
A preview rule that stays free of false positives is a candidate for promotion to enforce.
Inputs: since_hours. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
health_check is clearly distinct. enforce_denies vs preview_denies are differentiated by mode. home_region_denies is a specialized subset of enforced denies, which could be confused with enforce_denies, but the description clarifies its specific lens. daily_brief aggregates the others, but its purpose as a combined summary is evident from the description.
Tool names mix conventions: verb_noun (enforce_denies, preview_denies), noun_verb (health_check), noun_noun (home_region_denies), and adjective_noun (daily_brief). While all are snake_case, the inconsistent verb/noun order and variable parts of speech make naming less predictable.
5 tools is an appropriate scope for a specialized Cloud Armor deny analytics server. The count is neither too sparse to cover the core workflow nor bloated with redundant functionality, and each tool serves a distinct purpose within the defined domain.
The tools cover deny counts (enforced and preview), home-region analysis, and a summary brief, which addresses the primary monitoring workflow. However, there are notable gaps: no way to list or retrieve rule details to map priorities to rule names, and no allow-count or total-traffic metrics. These omissions could require agents to work around the lack of context when analyzing denies.
Maintenance
Related MCP Connectors
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Read-only Google Search Console MCP server for AI assistants.
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Read-only Google Analytics 4 MCP server for AI assistants.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceThis MCP Server provides a natural language interface to interact with Google's Policy Analyzer API, allowing users to analyze policies and evaluate compliance through conversations.-
- AlicenseNot gradedqualityDmaintenanceDefensive credential-exposure auditor for GKE that inventories workload identity, service account tokens, and RBAC posture, exposing findings via an MCP server at /mcp.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server for AI agent security guardrails. Provides input validation, prompt injection detection, PII redaction, output filtering, policy enforcement, rate limiting, and comprehensive audit logging.72 npm1MIT
- FlicenseNot gradedqualityDmaintenanceEnterprise MCP server for Google SecOps (Chronicle) SIEM/SOAR, enabling alert triage, UDM telemetry search, YARA-L detection rule management, log ingestion, and parser administration via Streamable HTTP.-