dawshund_mcp is an MCP server package used to enumerate AWS IAM data, evaluate effective permissions, and visualize access relationships among users, roles, and resources. It is aimed at cloud security engineers who want fast, simple, and effective insight into AWS identity risks. It is a wrapper around the dAWShund project, packaging the upstream project into two server forms and sparing users from having to remember and separately run multiple scripts.
The upstream dAWShund project provides three main components. sAWSage is used to enumerate IAM principals and resource policies and merge them into a single JSON document; supported resources include IAM groups, roles, and users, as well as some resource-based policies such as AWS Backup, EFS, KMS, Lambda, S3, SNS, and SQS. After running the script, the merged file sawsage.json is generated in the policies/ directory. Gerakina feeds the merged policies into AWS's simulate-principal-policy API and generates a new JSON file, effective_permissions.json, listing the actions each principal is allowed, explicitly denied, or implicitly denied; because it needs to call the AWS API for each unique combination of principal, action, and resource, this step may take some time. dAWShund then imports the effective permissions into a Neo4j database, builds a graph of principals and resources, and generates permissions4j.json and dawshund.json, suitable for browsing in Neo4j and BloodHound respectively. The Neo4j functionality is optional; the HTTP server included with this package provides a lightweight summary.
Regarding dependencies and environment requirements, dAWShund depends on Python, the AWS CLI, and several Python packages; to use Neo4j visualization, a running Neo4j instance is also required. Minimum requirements include: an AWS account with permissions to call the IAM API (for enumeration) and the simulate-principal-policy API (for evaluation), with AWS credentials configured using aws configure --profile <profile_name>; the AWS CLI installed and available in the path; optionally, if you plan to run the dawshund.py script directly,a Neo4j server is required (the HTTP server can aggregate results without Neo4j).
Installation method: first install the AWS CLI and configure a named profile for the account to be evaluated, for example aws configure --profile myprofile. Then clone this repository (or copy the mcp_dawshund_server folder) and run the installation script: cd mcp_dawshund_server followed by ./setup.sh. This script installs the Python dependencies (boto3, neo4j, flask, flask_cors) and clones the dAWShund code into a local subdirectory. If you want to use a Python virtual environment, you can create and activate it before running setup.sh.
Startup method: run python3 server.py to start the server; by default the HTTP service listens on port 8000 on all interfaces; you can set the PORT environment variable before startup to change the port, for example PORT=5000 python3 server.py. If you intend to use the MCP implementation instead of the HTTP API, you can run python3 iam_mcp_server.py; the MCP server does not bind a TCP port and communicates via standard input/output, and is usually started by clients such as Claude for Desktop.
HTTP server usage: the Flask-based server (server.py) exposes three endpoints over HTTP, and all requests and responses use JSON. First, enumerate IAM policies (/collect): trigger enumeration of IAM principals and resource policies via sAWSage; you need to provide the AWS CLI profile name, and optionally provide an array of regions; if no regions are provided, sAWSage will enumerate all known regions for supported services. The response is a large JSON document keyed by AWS ARN, where each entry contains metadata (friendly name, attached policies) and the raw statements extracted from inline and managed policies; the same file is also saved to dAWShund/policies/sawsage.json for later use. Second, evaluate effective permissions (/evaluate): use the AWS simulate-principal-policy API to simulate the permissions attached to each principal; this endpoint only requires the configurationFile name. The response contains the contents of effective_permissions.json, i.e., a dictionary keyed by principal ARN; the Permissions key in each entry contains lists named allowed, explicitDeny, and implicitDeny, listing the (action, resource) tuples for that principal. Third, summarize the evaluation results (/analyze): retrieve a compact summary of the evaluation; this endpoint reads effective_permissions.json and counts the number of allowed, explicitly denied, and implicitly denied actions for each principal, with no request body required. This summary helps quickly identify principals with excessive permissions or those with unexpected implicit denials. Deeper analysis can connect to a Neo4j database and run the original dawshund.py script, which will build the graph and create permissions4j.json and dawshund.json.
MCP server usage: In addition to the Flask HTTP API, this package also includes a Model Context Protocol (MCP) server implemented using the fastmcp library. The MCP server communicates via JSON-RPC and is intended for use by AI assistants such as Claude Desktop or custom FastMCP clients. It exposes the same operations as the HTTP API, but uses structured tool definitions instead of HTTP endpoints. Installing FastMCP: the setup.sh script installs the fastmcp package; if managing dependencies manually, you can install it yourself, and FastMCP requires Python 3.10 or later. Run the server manually to test locally: once running, it starts in STDIO mode, blocks, and listens for JSON-RPC requests on standard input; if you plan to expose it as a remote connector, it can also be run over HTTP. There are three available tools, each returning JSON structured content with a brief summary; the collect and evaluate tools return a short message and the path to their respective JSON output files (full documentation may reach hundreds of KB), and the analyze tool reads the effective permissions file and returns a dictionary keyed by principal ARN containing counts of allowed and denied actions.
Integration with Claude Desktop: Claude Desktop can launch a local MCP server defined in the claude_desktop_config.json file. On macOS this file is located at ~/Library/Application Support/Claude/claude_desktop_config.json; add a new entry under the mcpServers key and replace it with the correct path on your system. After saving, restart Claude Desktop, because the configuration is only read at startup. When a natural language prompt requires IAM enumeration or permission simulation, Claude will call the corresponding tool. For example, you can say: "Enumerate IAM policies for my default profile and summarise how many actions are allowed or denied." Claude will issue collect_iam, evaluate_iam, and analyze_iam calls in sequence, and the results of each tool are returned to Claude and incorporated into the assistant's final reply. You can also use the MCP server as a remote connector, run it over HTTP, and register the URL in the Claude web interface, for example by adding it in Claude settings: http://localhost:8000/mcp As a custom connector.
Notes and limitations: Regarding permission requirements, the enumeration steps use IAM APIs such as list_users, list_roles, get_user_policy, etc.; the evaluation step calls simulate-principal-policy, which evaluates actions against resources; ensure that the AWS profile used has sufficient permissions to perform these operations. Regarding runtime and cost, policy simulation can be time-consuming because one API call is made for each principal/action/resource combination; for accounts with many principals and policies, it may take several minutes; the simulation APIs themselves do not incur additional AWS charges, but enumeration queries are subject to normal API rate limits. Regarding Neo4j integration, the default dawshund.py connects to a Neo4j instance on localhost:7687, with username neo4j and password dawshund; to populate your own Neo4j database, edit the NEO4J_URI and NEO4J_AUTH values in dAWShund/dawshund.py before running; the HTTP server provided here does not use Neo4j at all, and instead aggregates JSON output. Regarding extensibility, the upstream project currently only enumerates resource policies for a limited set of services; to cover more services, consider contributing service enumerators to the upstream repository. Regarding licensing, the dAWShund script bundled with this package is under the BSD 3-Clause license; the wrapper code in this folder (server and installation scripts) has been released into the public domain.
