Quickstart

From zero to a working Ansible-backed MCP tool in three steps. This guide uses localhost; the same steps apply to any remote host by editing the inventory.

Prerequisites: Python 3.12+, and SSH access to the hosts you want to automate (localhost works out of the box via the local connection).
1

Install

pip install rocannon

This installs ansible-core and ansible-runner alongside Rocannon. Verify the environment:

rocannon doctor

You should see all binaries (ansible-doc, ansible-inventory, ansible-runner) marked [ ok ].

2

Scaffold a profile

rocannon quickstart

This writes two files under .rocannon/:

.rocannon/quickstart.yml Profile declaring localhost inventory and a handful of builtin modules
.rocannon/inventory.ini Inventory pinning localhost to the same Python interpreter Rocannon uses

Confirm the tools registered:

rocannon mcp doctor --profile .rocannon/quickstart.yml

Output shows the tool count, resource count, and prompt count for the server as your MCP client will see it.

3

Wire your MCP client

Claude Code (recommended for first use):

claude mcp add rocannon -- rocannon mcp serve --profile /absolute/path/to/.rocannon/quickstart.yml

Or add to .mcp.json (Claude Code, Cursor, any client that reads it):

{
  "mcpServers": {
    "rocannon": {
      "command": "rocannon",
      "args": ["mcp", "serve", "--profile", "/absolute/path/to/.rocannon/quickstart.yml"]
    }
  }
}

Use an absolute path. MCP clients launch the server from their own CWD, not yours.

First conversation

In Claude Code (or whichever client you wired), try:

Gather facts from localhost and tell me the OS and kernel version.

Rocannon runs ansible.builtin.setup against localhost and returns the structured fact output. The assistant can then answer in plain English.

Without an LLM

The REPL drives the same server in-process, no MCP client needed:

rocannon repl --profile .rocannon/quickstart.yml
rocannon> setup target=localhost
rocannon> .save my-first-session "gather facts from localhost"

The .save command writes the session to .rocannon/playbooks/my-first-session.yml, a standard Ansible playbook that runs without Rocannon.

Next steps

  • Add more modules: edit the profile's modules: list to include collections like community.docker or amazon.aws. Profile reference →
  • Point at real hosts: replace the localhost inventory with your actual SSH inventory.
  • Add multiple profiles for different environments (dev/staging/prod) and switch at runtime with rocannon_use_profile.
  • Use check=true on any module call to preview what would change before applying it.