Ara Records

You can use this MCP server to access Ara Records API data from Claude Code, enabling monitoring and analysis of Ansible playbook executions through a dedicated MCP interface. It exposes Ara Records endpoints as MCP resources and provides tools to query, monitor, and manage playbooks, plays, tasks, and results in a structured, paginated way.

How to use

You interact with the Ara Records MCP server by configuring it in your Claude Code environment and then calling its exposed resources and tools. Start by ensuring the Ara API is reachable at the configured base URL, then use the provided resources to list playbooks, plays, tasks, and hosts, or use the tools to monitor a specific playbook’s progress, query arbitrary endpoints, or delete records.

How to install

Prerequisites you need before installing: Node.js version 18.0.0 or higher, and a running Ara API locally at http://localhost:8000 by default.

Install via npx (recommended): install and register the MCP using Claude Code, then run the MCP package with npx.

# Local installation (project-specific, default)
claude mcp add ara-api -- npx -y @ultroncore/ara-records-mcp

# User installation (available globally for your user)
claude mcp add --scope user ara-api -- npx -y @ultroncore/ara-records-mcp

Additional installation options

With a custom Ara server address, you can point the MCP to the remote API server.

claude mcp add --scope user ara-api -- npx -y @ultroncore/ara-records-mcp --api-server http://ara.example.com:8080

Alternate authentication and concurrency examples

If authentication is required, provide credentials so HTTP Basic Authentication is used when the Ara API is protected behind a reverse proxy.

claude mcp add --scope user ara-api -- npx -y @ultroncore/ara-records-mcp --api-server https://ara.example.com --username admin --password secret

Manual configuration snippets

Configure the MCP server in Claude Code by specifying the command, arguments, and environment variables in your .mcp.json file.

{
  "mcpServers": {
    "ara-api": {
      "command": "node",
      "args": ["node_modules/ara-records-mcp/ara-server.js"],
      "env": {
        "ARA_API_SERVER": "http://localhost:8000"
      }
    }
  }
}

What to expect after installation

Restart Claude Code after installing the MCP server to load the new resources and tools. Then you can explore resources such as ara://playbooks, ara://plays, ara://tasks, ara://hosts, ara://results, ara://latesthosts, and ara://running, and use the provided tools to query and monitor playbooks.

Configuration and access details

The server connects to Ara REST API endpoints and supports automatic pagination, default limits, and smart ordering to manage large result sets efficiently. It provides both read-only resources and tooling for in-depth queries and real-time-style monitoring through polling.

Security and authentication

HTTP Basic Authentication is supported for scenarios where the Ara API sits behind a proxy that handles authentication. You can enable it by supplying a username and password, either through environment variables or CLI arguments.

Examples of common usage patterns

Default usage pattern for querying data uses automatic pagination with a default limit of 10 results per request and automatic ordering by start time. You can override these with explicit query parameters.

To monitor a specific playbook, you can start a watch operation that returns detailed progress, including tasks and timing information.

Troubleshooting notes

Ensure the Ara API is running and accessible at the configured base URL. If the MCP server reports startup issues, verify that the Node.js version matches the minimum requirement and that the environment variables are correctly set.

Notes on real-time monitoring

Ara does not provide WebSocket support, so monitoring is based on a polling approach. Use the ara://running resource to identify in-progress playbooks and then call get_playbook_status or watch_playbook for detailed progress and task-level data.

Version history highlights

Initial release includes basic authentication support, real-time monitoring via polling, automatic pagination, MCP SDK-based schema, and token-safe responses.

Available tools

ara_query

Query Ara API endpoints with GET/POST support and automatic pagination

watch_playbook

Monitor a specific playbook execution with detailed progress tracking, task completion status, and execution timeline

get_playbook_status

Get a quick summary of playbook execution status without detailed task information

delete_playbook

Delete a single playbook record and all associated plays, tasks, and results

delete_playbooks_bulk

Delete multiple playbook records concurrently with configurable concurrency limit