evoctl

Give your scripts and AI agents a direct line to Evolution API. Connect a deployment, find a conversation, send a message, and inspect its receipt—from your terminal or an MCP client.

Quickstart

Install with uv and Python 3.12+. You'll need an existing Evolution API deployment.

uv tool install 'git+https://github.com/1vecera/evoctl.git'

Connect to its Docker container on a remote host:

evoctl remote add mini --ssh user@your-host --docker
evoctl remote connect mini
evoctl status

The first profile becomes your default. The remote needs uv, SSH access, and Docker access. For a local container, omit --ssh; for an HTTPS endpoint, use --url and --key-env. See connection options and SSH key setup. Pin a commit SHA in the install URL for reproducible deployments.

Your next commands

evoctl chats search "Alex"  # people and groups together
evoctl chats list --limit 10
evoctl messages read 15550000001 --limit 10
evoctl messages send 15550000001 --text "Hello Alex" --request-id hello-alex
evoctl messages status MESSAGE_ID

The number is an example. Resolve the intended recipient and use the exact reviewed text. Reuse the same request ID for the same logical send; pending is an API receipt, not delivery confirmation.

evoctl pair --open
evoctl ui --open
evoctl status --watch
evoctl services start
evoctl --profile another-remote status

Pairing uses WhatsApp's Linked devices screen. GUI forwarding binds to local loopback. Service commands manage existing containers; a Colima profile can also start its VM. See the complete command reference and troubleshooting.

Related MCP server: Evolution API MCP Server

Local contacts

Find saved names, even without diacritics. WhatsApp can show a full address-book name while Evolution returns only a profile first name. Export your contacts once and import them into evoctl's built-in local directory:

evoctl contacts import ~/Downloads/contacts.csv --dry-run
evoctl contacts import ~/Downloads/contacts.csv
evoctl contacts list --query "novak"   # search local names offline
evoctl chats search "Alex Novak"      # find WhatsApp recipients using those names

Alex Novak matches Alex Novák; uppercase queries work too. CLI and MCP share the same private directory for the selected deployment. Local lookup works without a WhatsApp connection, and imported names also appear in remote searches and chat listing. A local entry alone does not confirm WhatsApp membership.

Inspect the preview's skipped-row and conflict counts before importing. Numbers need a + or 00 international prefix by default; use --region CZ only if national numbers in the file should be interpreted as Czech numbers. Existing local names are preserved unless --replace is explicit. Numbers shared by different names are skipped, and email-only records stay in the original export.

No Google or Microsoft login is needed in evoctl. To refresh your list, export again and repeat the import. For one confirmed recipient, use evoctl contacts name 15550000001 "Alex Novák"; --clear removes its saved name. Export guides, supported CSV formats and import options →

Three tools for your agent

Discover → read → write. That is the entire MCP surface, including administrative mode. Workflow and API schemas are fetched on demand, and every call still goes through the shared operation validator.

Add this to your MCP client's configuration after installing evoctl:

{
  "mcpServers": {
    "evoctl": {
      "command": "evoctl",
      "args": ["mcp", "serve", "--mode", "write"]
    }
  }
}

Use the executable's absolute path if your client doesn't inherit your shell's PATH. The CLI can generate this configuration with evoctl mcp config --mode write.

An agent calls evoctl_discover with {"operation":"messages_read"} to get the exact schema, then calls evoctl_read with:

{
  "action": "messages_read",
  "arguments": {"chat": "15550000001@s.whatsapp.net", "limit": 10}
}

Use read action contacts_list for offline contact lookup and write action contacts_import for CSV text; discover their argument schemas first. Use action: "api" for a catalog operation. Read mode exposes only discovery and reading. Write mode adds messaging, pairing, and local contact imports and edits. Admin mode also permits remote setup, service control, and administrative API calls. A mutation cannot bypass those boundaries through the read tool. MCP examples and capability details →

The whole REST catalog, within reach

Discover 182 routes from Evolution API 2.3.7: messages, media, groups, calls, labels, business settings, webhooks, and bot integrations.

evoctl api list --query group
evoctl api schema group.fetch_all_groups
evoctl api call group.fetch_all_groups --query '{"getParticipants":false}'

The catalog works offline. Agents use the same search and schemas through evoctl_discover. Read permissions follow what an operation does, including lookup POSTs and state-changing GETs. Explore the API contract →

Built for real messaging workflows

• One contract across CLI and MCP. Structured JSON, bounded results, explicit pagination, and actionable errors.

• Duplicate-send protection. A SQLite ledger reserves your request ID before a mutation leaves the process. Concurrent callers sharing that ledger cannot repeat the same send.

• Honest delivery status. Pending, server acknowledgment, delivery, and read receipts remain distinct. An uncertain attempt stays reserved for inspection.

• Credentials stay out of profiles. Use environment/container references; responses redact known secrets. SSH honors host-key verification.

• Read without changing read state. Contact and history lookups don't send read receipts.

The ledger is local, so separate state directories don't share duplicate protection. Evolution is installed separately. Some upstream schemas are advisory; binary multipart uploads and event subscriptions are outside this release. See security and trust boundaries and API limitations.

Build with us

Try evoctl against your existing deployment. Found a route that behaves differently? Report it with the Evolution version and operation name, or contribute a fix.

Design decisions and source research · Local and hosted verification · Brand assets

MIT licensed. Independently developed by Daniel Vecera. This project uses Evolution API, a separately licensed service; no affiliation with Evolution API, WhatsApp, or Meta is implied. License · Notice