arvancai

ArvanCloud MCP server + Agent Skill — manage ArvanCloud from any MCP-capable agent/IDE
(Cursor, Windsurf, Claude Desktop/Code, Codex, OpenCode, and more).

npm install -g arvancai

Repository: https://github.com/0xamirreza/arvancai
npm: https://www.npmjs.com/package/arvancai
Version: 0.6.1

Requires Node.js ≥ 20 and an ArvanCloud Machine User API key:
https://docs.arvancloud.ir/en/accounts/iam/machine-user

Any Agent / IDE  ──►  Skill (workflows)  +  MCP tools
                              │
                              ▼
                    arvancai (stdio MCP server)
                     │                      │
                     ▼                      ▼
          napi / OpenAPI (local)    mcp.arvancloud.ir (bridged)
          CDN · DNS · IaaS · …      Cloud Logs mgmt (+ future toolsets)

1) Install (auto-wires clients)

export ARVANCLOUD_API_KEY="your-machine-user-key"   # optional but recommended
npm install -g arvancai

On global install, arvancai automatically:

• merges itself into Cursor ~/.cursor/mcp.json (keeps your other MCP servers)
• copies the Agent Skill to ~/.cursor/skills/arvancai/
• wires Windsurf / Claude Desktop / Codex / OpenCode when their config directories already exist

Re-run anytime (e.g. after setting the API key):

export ARVANCLOUD_API_KEY="your-machine-user-key"
arvancai setup

Force every known host path (even if the app is not installed yet):

arvancai setup --all

Skip auto-setup during install:

ARVANCAI_SKIP_SETUP=1 npm install -g arvancai

Check CLI (this must print help — it must not hang):

arvancai --help
which arvancai

Then reload Cursor (or reopen MCP settings) so arvancai shows up under MCP and Skills.

With no arguments, arvancai speaks MCP over stdio (for IDEs). Do not use it as a chat CLI.

2) API key & extras

export ARVANCLOUD_API_KEY="your-machine-user-key"

The env may be a bare UUID or already prefixed (Apikey … / apikey … / Bearer …).
Local tools always send Authorization: Apikey <uuid>.
The official MCP bridge sends Arvancloud-Api-Key: apikey <uuid>.

Optional Object Storage (S3 HMAC):

export ARVANCLOUD_S3_ACCESS_KEY_ID="..."
export ARVANCLOUD_S3_SECRET_ACCESS_KEY="..."

Useful flags:

# Inventory / diagnosis only — blocks POST/PUT/PATCH/DELETE + S3 writes + bridged write tools
export ARVANCLOUD_READ_ONLY=1

# Disable hosted MCP bridge (Cloud Logs management)
export ARVANCLOUD_OFFICIAL_MCP=0

# Restrict bridged toolsets (default: all)
export ARVANCLOUD_OFFICIAL_MCP_TOOLSETS=logs

See .env.example. If setup ran without a key, configs keep <MU-KEY> until you re-run arvancai setup with the env set.

3) Manual MCP (optional)

Auto-setup is enough for most users. Manual shape (also under examples/):

{
  "mcpServers": {
    "arvancai": {
      "command": "arvancai",
      "env": {
        "ARVANCLOUD_API_KEY": "<MU-KEY>"
      }
    }
  }
}

You do not need a separate arvancloud remote MCP entry for Logs — arvancai bridges mcp.arvancloud.ir by default. Official docs: developer-tools/mcp.

GUI apps that lack your shell PATH are fine: arvancai setup writes an absolute node + bin/arvancai.js path.

4) Skill vs MCP

| Piece | Role | Portability | | ----- | ---- | ----------- | | MCP (arvancai) | Tools / resources / prompts over the MCP protocol | Works on all MCP clients | | Skill (skill/SKILL.md) | Agent playbook (tool choice, TLS/acme.sh, Iran DNS gotchas, safety) | Best on Cursor-style Agent Skills; elsewhere paste/link as project instructions |

MCP alone is enough for tool calling. Skill improves agent behavior where the host supports skills/rules.

Coverage (short)

Official portal: https://www.arvancloud.ir/fa/dev/api

| Area | Status | | ---- | ------ | | CDN / DNS / Security / reports | Yes (+ invoke_cdn_api) | | DNS zone import/export | import_dns_zone / export_dns_zone | | Cloud Server (ECC) / partial DBaaS | Yes | | IaaS region quota | get_region_quota (limits, not wallet) | | Object Storage (S3 + management API) | Yes | | VOD / LIVE / Video Ads | Yes | | Edge Computing | Yes | | Cloud Container (CaaS) | Yes | | AI-as-a-Service | Yes | | CloudLogs ingest | write_cloud_logs (local) | | CloudLogs management (spaces / sinks / forwarders) | Official hosted MCP bridge (mcp.arvancloud.ir) | | Let's Encrypt DNS-01 (acme.sh) | Documented in Skill (skill/references/dns.md) | | Drive / Accounts / Changelog | No public REST OpenAPI |

Details: ARCHITECTURE.md, docs/bridge-official-mcp.md, CHANGELOG.md, docs/, skill/SKILL.md.

Security

• Never commit API keys.
• Prefer READ tools first; destructive tools need exact IDs.
• Use ARVANCLOUD_READ_ONLY=1 for audit-only agents.
• See SECURITY.md.

Local development

git clone https://github.com/0xamirreza/arvancai.git
cd arvancai
npm install
npm run build
npm test
export ARVANCLOUD_API_KEY=...
npm start
# wire this checkout into clients:
ARVANCAI_AUTO_SETUP=1 node scripts/postinstall.mjs
# or:
node dist/index.js setup

See DEVELOPMENT.md.

License

MIT