ArvanCloud MCP Server

<p align="center"> <img src="assets/banner.svg" alt="ArvanCloud MCP" width="100%"> </p>

<h1 align="center">ArvanCloud MCP Server</h1>

<p align="center"> <img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white"> <img alt="MCP" src="https://img.shields.io/badge/MCP-server-7b5cff"> <img alt="Tools" src="https://img.shields.io/badge/tools-229-0aa"> <img alt="Tests" src="https://img.shields.io/badge/tests-passing-2ea44f?logo=pytest&logoColor=white"> <img alt="License" src="https://img.shields.io/badge/license-MIT-green"> </p>

A Model Context Protocol (MCP) server that gives MCP-compatible clients — Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, and any other MCP host — full control of the ArvanCloud platform through natural language, plus a cloud-DevOps toolbox (provisioning, Kubernetes, IaC, security, networking, tasks).

It talks to ArvanCloud's unified API (napi, https://napi.arvancloud.ir) and exposes both ergonomic, typed tools for the common operations of every product and a generic escape-hatch tool that can reach any endpoint — so the whole platform is usable, today and as the API grows.

Independent, community-built integration. Not an official ArvanCloud product.

Covered products

220+ tools across 20 service groups — the whole ArvanCloud platform plus a cloud-DevOps toolbox: provision a server, SSH in, validate IaC, deploy to Kubernetes, scan for security issues, run networking diagnostics, schedule background jobs, and send notifications — with guardrails, metrics, and reusable workflow prompts on top.

ArvanCloud platform:

Service group	Tools cover	API base
compute	Cloud Servers (Abrak): create/delete, power & maintenance actions, rename/rebuild/resize, wait_for_server, images, plans, quotas, SSH keys, tags, server↔security-group, PTR	/ecc/v1
network	Private networks & subnets (CRUD), security groups & rules, floating IPs (incl. delete), port security	/ecc/v1
storage	Block volumes & snapshots, attach/detach, limits	/ecc/v1
objectstorage	S3-compatible: buckets, objects (text/binary), copy, presigned URLs, policies/ACLs	s3.<region>.arvanstorage.ir
cdn	Domains, caching, purge, page rules, firewall/WAF, rate-limit, log forwarders, metric exporters, SSL, apps (CRUD + webhook)	/cdn/4.0
dns	DNS records (A/CNAME helpers), cloud/proxy toggle, zone import, DNSSEC	/cdn/4.0
vod	Channels, videos, audios, subtitles, watermarks, profiles, files, user domain (full CRUD)	/vod/2.0
live	Live Streaming channels & inputs	/live/2.0

DevOps & automation toolbox:

Service group	Tools cover
ssh	Run commands/scripts, upload/download files, connection checks (asyncssh)
provision	arvan_provision_server: create + wait + SSH-install / cloud-init in one call
k8s	kubectl apply/delete/get, generic kubectl, Helm install/uninstall (any cluster incl. ArvanCloud PaaS)
iac	Terraform validate/fmt/plan/apply/destroy, tflint, checkov, kubeconform, kube-linter, hadolint, yamllint, trivy
security	Secret/vuln/SBOM/SAST scans (gitleaks, trivy, syft, semgrep), security-group auditing, HTTP-header grading, password & SSH-keypair generation
net	DNS, reverse DNS, TCP/port checks, HTTP checks, TLS-cert inspection, ping/traceroute/whois, HTTP load test
git	Clone & inspect repos (validate/deploy IaC from a repo)
tasks	Run any tool in the background, on a delay or recurring schedule; poll status; announce completion via webhook
notify	Send messages to Slack, Telegram, a generic webhook, or email (SMTP)
observability	arvan_metrics (JSON + Prometheus), arvan_audit_log, optional per-minute rate limiting
common	arvan_request (reach any endpoint), arvan_capabilities, arvan_doctor, plus workflow prompts & live resources

Guardrails: every tool is annotated readOnlyHint/destructiveHint so clients can tell safe from dangerous calls. Set ARVAN_READ_ONLY=true to expose only read tools (and restrict arvan_request to GET), or scope the surface with ARVAN_TOOLS_ALLOW / ARVAN_TOOLS_DENY (glob lists).

Prompts & resources: reusable prompts (provision_web_server, audit_security, setup_cdn, deploy_static_site) and live MCP resources (arvan://regions, arvan://servers/{region}, arvan://domains, arvan://capabilities).

iam and container (Kubernetes PaaS) are documentation pointers — manage them via the panel / kubectl / arvan_request.

100% napi coverage: the generic arvan_request tool can call any ArvanCloud endpoint and arvan_capabilities lists them, so nothing is out of reach even without a dedicated typed tool. Run arvan_doctor to see what's configured and which optional CLI tools are installed.

<p align="center"><img src="assets/services.svg" alt="Service groups" width="100%"></p>

Architecture

<p align="center"><img src="assets/architecture.png" alt="Architecture" width="78%"></p>

AI agents talk to the server over MCP (stdio locally, or streamable-HTTP when deployed). The server wraps ArvanCloud's napi for the platform products and shells out to standard tools (terraform, kubectl, ansible, trivy, …) for the DevOps toolbox. For many concurrent users it runs stateless behind a load balancer and scales horizontally:

<p align="center"><img src="assets/deployment.png" alt="Scalable deployment" width="78%"></p>

Every tool call flows through the same guardrails + observability path:

<p align="center"><img src="assets/request_lifecycle.png" alt="Tool-call lifecycle" width="80%"></p>

Diagrams are generated with the diagrams library — regenerate with make diagrams (needs Graphviz).

Requirements

• Python 3.10+
• An ArvanCloud machine-user access key (create one in the panel under Settings → Machine User / API keys). See the API usage docs.

Install

git clone https://github.com/dwin-gharibi/arvancloud-mcp.git
cd arvan-temp
pip install .          # or:  pip install -e ".[dev]"  for development

Configure

All configuration is via environment variables (see .env.example):

Variable	Default	Description
ARVAN_API_KEY	—	Required. Machine-user access key. The Apikey prefix is added automatically.
ARVAN_BASE_URL	https://napi.arvancloud.ir	API host (use the .com alias if needed).
ARVAN_DEFAULT_REGION	—	Default IaaS region, e.g. ir-thr-c2, so you don't repeat it.
ARVAN_ENABLED_SERVICES	all	Comma list of tool groups to expose (common is always on).
ARVAN_TIMEOUT	60	Per-request timeout (seconds).
ARVAN_MAX_RETRIES	4	Retries for network errors / 429 / 5xx.
ARVAN_BACKOFF_FACTOR	1.0	Exponential backoff base (seconds).
ARVAN_VERIFY_SSL	true	TLS verification.
ARVAN_TRANSPORT	stdio	stdio, sse, or streamable-http.
ARVAN_HOST / ARVAN_PORT	127.0.0.1 / 8000	Bind address for HTTP transports.
ARVAN_S3_ACCESS_KEY / ARVAN_S3_SECRET_KEY	—	Object Storage credentials (separate from the API key).
ARVAN_S3_REGION / ARVAN_S3_ENDPOINT	ir-thr-at1	S3 region (selects the endpoint) or an explicit endpoint URL.
ARVAN_SSH_USER	root	Default SSH user for the remote-exec tools.
ARVAN_SSH_KEY / ARVAN_SSH_KEY_FILE / ARVAN_SSH_PASSWORD	—	Default SSH auth (inline key, key file, or password).
ARVAN_SSH_PORT / ARVAN_SSH_KNOWN_HOSTS / ARVAN_SSH_TIMEOUT	22 / off / 30	SSH port, host-key file (off = no verification), connect timeout.

Run

Local (stdio) — for Claude Desktop / Claude Code

export ARVAN_API_KEY="your-machine-user-key"
export ARVAN_DEFAULT_REGION="ir-thr-c2"
arvancloud-mcp                      # or:  python -m arvancloud_mcp

See Add it to your AI agent below for per-client setup.

Networked (HTTP) — for remote/shared deployments

ARVAN_API_KEY=your-key ARVAN_TRANSPORT=streamable-http ARVAN_HOST=0.0.0.0 \
  arvancloud-mcp
# Streamable-HTTP endpoint: http://localhost:8000/mcp

Docker

docker build -t arvancloud-mcp .
docker run --rm -p 8000:8000 -e ARVAN_API_KEY=your-key arvancloud-mcp

Or with Compose (reads ARVAN_API_KEY from your environment or .env):

ARVAN_API_KEY=your-key docker compose up --build

To bundle the IaC/security validators (terraform, checkov, hadolint, trivy, …):

docker build --build-arg INSTALL_IAC_TOOLS=true -t arvancloud-mcp:iac .

Add it to your AI agent

All of these run the server over stdio. Install it first (pip install arvancloud-mcp) so the arvancloud-mcp command is on PATH.

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "arvancloud": {
      "command": "arvancloud-mcp",
      "env": { "ARVAN_API_KEY": "Apikey ...", "ARVAN_DEFAULT_REGION": "ir-thr-c2" }
    }
  }
}

Claude Code (CLI):

claude mcp add arvancloud --env ARVAN_API_KEY="Apikey ..." -- arvancloud-mcp

Cursor — ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "arvancloud": { "command": "arvancloud-mcp", "env": { "ARVAN_API_KEY": "Apikey ..." } }
  }
}

VS Code — .vscode/mcp.json:

{
  "servers": {
    "arvancloud": { "type": "stdio", "command": "arvancloud-mcp", "env": { "ARVAN_API_KEY": "Apikey ..." } }
  }
}

Gemini CLI — ~/.gemini/settings.json:

{
  "mcpServers": {
    "arvancloud": {
      "command": "arvancloud-mcp",
      "env": { "ARVAN_API_KEY": "Apikey ..." },
      "timeout": 60000
    }
  }
}

Tip: for a safe, sharable setup, add "ARVAN_READ_ONLY": "true" to env so only read tools are exposed, or scope with ARVAN_TOOLS_ALLOW / ARVAN_TOOLS_DENY. Remote (HTTP) clients point at http://<host>:8000/mcp instead of a command.

Deploy & scale

Production manifests live in deploy/: Kubernetes with an HPA (deploy/kubernetes, kubectl apply -k), a Helm chart (deploy/helm/arvancloud-mcp), and Terraform that provisions an ArvanCloud server running the MCP (deploy/terraform). For many concurrent loads, run the HTTP transport with ARVAN_STATELESS_HTTP=true ARVAN_JSON_RESPONSE=true and scale replicas (the HPA does 2→10 on CPU/memory).

CI/CD

GitHub Actions in .github/workflows:

• ci.yml — ruff + mypy + pytest (with coverage) + the MCP smoke test, on Python 3.10–3.12.
• docker.yml — build & push the image to GHCR.
• security.yml — Trivy filesystem scan.
• release.yml — on a v* tag: build & publish to PyPI, create a GitHub release, and publish to the MCP registry (see Publishing).

<p align="center"><img src="assets/cicd.png" alt="CI/CD pipeline" width="80%"></p>

Usage examples (what you can ask)

Platform:

• "List my cloud servers in ir-thr-c2 and power off the one named staging."
• "Create an A record for www on example.com → 1.2.3.4, proxied; enable free SSL."
• "Add a 50 GB volume and attach it to server abcd."
• "Upload ./site to bucket assets and host it as a static website."
• "Purge the CDN cache for example.com and show the caching settings."

DevOps:

• "Provision a 2-CPU Ubuntu server, install Docker, and Slack me when it's ready."
• "Validate this Terraform and show the plan; if it's clean, apply it." → arvan_iac_*:

<p align="center"><img src="assets/iac_pipeline.png" alt="IaC validate to apply" width="82%"></p>

• "Apply deploy/kubernetes to my cluster with this kubeconfig." → arvan_k8s_apply.
• "Audit my security groups and grade https://example.com headers." → arvan_security_*.
• "Load-test https://example.com with 200 requests at concurrency 20." → arvan_net_http_load_test.
• "Search the ArvanCloud docs for DNSSEC and summarise the page." → arvan_docs_*.

Meta:

• "What ArvanCloud features can you control?" → arvan_capabilities.
• "Find the tool for floating IPs." → arvan_find_tool.
• "Is everything configured?" → arvan_doctor. "Show tool metrics." → arvan_metrics.

Background jobs & scheduling

<p align="center"><img src="assets/tasks_flow.png" alt="Background tasks flow" width="78%"></p>

Long-running work (provisioning, IaC apply, scans, load tests) can run in the background so the conversation isn't blocked:

arvan_task_submit(tool="arvan_provision_server", arguments={...},
                  announce_webhook="https://hooks.example.com/done")
# -> returns a task id immediately; poll with arvan_task_status, or get a
#    webhook POST when it finishes. Recurring schedules: interval_seconds=3600.

Concurrency and history are bounded (ARVAN_TASK_MAX_CONCURRENCY, ARVAN_TASK_MAX_TASKS); the webhook announcement is replica-independent, so it works behind a load balancer at scale.

End-to-end: provision a server and configure it

"Spin up a small Ubuntu server in ir-thr-c2, then install nginx on it."

<p align="center"><img src="assets/provision_flow.png" alt="Provisioning flow" width="85%"></p>

arvan_provision_server does this in one call, or the model can chain:

1. arvan_list_plans + arvan_list_images → pick a flavor and Ubuntu image.
2. arvan_create_ssh_key (or reuse) → arvan_create_server(..., ssh_key_name=...).
3. arvan_wait_for_server → waits until it's active and returns the public IP.
4. arvan_ssh_run_script(host=ip, script="apt-get update && apt-get install -y nginx").

That's the full lifecycle — buy → boot → SSH in → run commands — in one place.

The generic tool

For anything not wrapped explicitly (e.g. Live Streaming, or new endpoints):

arvan_request(method="GET", path="/live/2.0/channels")
arvan_request(method="POST", path="/cdn/4.0/domains/example.com/page-rules",
              body={"url": "example.com/*", "actions": {"cache_level": "bypass"}})

Discover paths first with arvan_capabilities("cdn"), arvan_capabilities("vod"), etc.

Notes on Object Storage, SSH, IAM & Containers

• Object Storage is S3-compatible (https://s3.<region>.arvanstorage.ir) and uses its own access/secret key. The arvan_s3_* tools wrap it via boto3 — set ARVAN_S3_ACCESS_KEY / ARVAN_S3_SECRET_KEY (+ region/endpoint).
• SSH tools run real commands on your servers. Host-key verification is off by default (freshly provisioned servers aren't in any known_hosts); set ARVAN_SSH_KNOWN_HOSTS to enforce it. Treat command execution as privileged — confirm intent before running destructive commands.
• IAM (machine users, roles) and Cloud Container (Kubernetes PaaS, driven by kubectl/oc) aren't wrapped as typed tools; manage IAM via the panel or arvan_request, and Containers via the Kubernetes API.

Development & tests

pip install -e ".[dev]"
pytest

The test suite runs fully offline: HTTP is mocked with respx, and the boto3 (Object Storage) and asyncssh (SSH) clients are stubbed. It verifies auth header normalization, retry/backoff, error handling, region defaulting, request-body construction (incl. multipart zone import), Object Storage put/get/list, SSH run/script/upload/download, config parsing, tool registration, and the generic request path.

Project layout

src/arvancloud_mcp/
  config.py        # env-driven settings (API, S3, SSH, transport)
  client.py        # async httpx client: auth, retries, JSON+multipart, errors
  catalog.py       # machine-readable API catalogue (powers arvan_capabilities)
  server.py        # FastMCP assembly + transport selection
  tools/
    common.py        # generic request + capabilities
    compute.py       # servers, actions, images, plans, ssh-keys, tags, wait
    network.py       # networks, security groups, floating IPs, ports
    storage.py       # block volumes & snapshots
    objectstorage.py # S3 buckets & objects (boto3)
    cdn.py           # domains, caching, rules, rate-limit, observability
    dns.py           # records, cloud toggle, zone import, DNSSEC
    vod.py / live.py # video on demand / live streaming
    ssh.py           # run commands & transfer files over SSH (asyncssh)
tests/             # offline tests (respx + mocked boto3/asyncssh)

Publishing & marketplaces

The repo is set up to publish itself:

• PyPI — release.yml builds and publishes arvancloud-mcp on a v* tag (PyPI Trusted Publishing; no token in the repo). Most MCP marketplaces (Glama, PulseMCP, mcp.so, Smithery) index from PyPI/GitHub automatically.
• Official MCP Registry — server.json is the registry manifest (io.github.dwin-gharibi/arvancloud-mcp). The release workflow runs mcp-publisher (GitHub OIDC) to publish it; the mcp-name marker is embedded at the top of this README for PyPI validation. See the registry publishing guide.

To cut a release: bump version in pyproject.toml, server.json, and the badge, then git tag v0.1.0 && git push --tags.

License

MIT — see LICENSE.

<p align="center"> <img src="assets/logo.svg" alt="ArvanCloud Logo" width="100%"> </p>