@gnaws/mcp

Let your AI agent see what's beneath your cloud.

MCP (Model Context Protocol) server for @gnaws/core — expose AWS resource scanning, graph building, and unused resource detection as tools for AI agents.

What is this?

An MCP server that gives AI agents (Claude, Kiro, Cursor, etc.) the ability to:

• Scan your AWS account and build a resource relationship graph
• Load previously dumped data for offline analysis
• Detect unused/orphaned resources (detached volumes, unassociated IPs, empty load balancers, etc.)
• Export the graph to GEXF (Gephi), JSON (sigma.js), or Markdown
• Dump raw resource data for later use

Installation

npm install -g @gnaws/mcp
# or run without installing:
npx @gnaws/mcp

Requires Node.js >= 24.

MCP Client Configuration

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "gnaws": {
      "command": "npx",
      "args": ["@gnaws/mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gnaws": {
      "command": "npx",
      "args": ["@gnaws/mcp"]
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "gnaws": {
      "command": "npx",
      "args": ["@gnaws/mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "gnaws": {
      "command": "npx",
      "args": ["@gnaws/mcp"]
    }
  }
}

Available Tools

| Tool | Description | Requires | |------|-------------|----------| | status | Check server state (loaded? how many nodes/edges?) | — | | scan | Scan AWS resources live with a profile | AWS credentials | | load | Load from a dump directory (offline) | Dump path | | detect | Find unused/orphaned resources | scan or load | | export | Export graph to gexf/json/md/csv | scan or load | | dump | Save raw data for offline use | scan or load | | regions | List enabled AWS regions | scan or load |

Example Conversations

User: Show me the unused resources in my AWS account
Agent: calls scan with profile → calls detect → presents findings

User: Load the dump from ./data and export a graph
Agent: calls load with path → calls export with format "gexf"

User: What's the state of the gnaws server?
Agent: calls status → reports no data loaded, suggests scan or load

Features

• Progress notifications — long-running scans report progress to the agent
• Error handling — every tool returns structured errors with actionable guidance
• Workflow guidance — tool responses tell the agent what to call next
• Offline mode — load from dumps without AWS credentials
• 81 AWS services — EC2, Lambda, S3, RDS, ECS, EKS, DynamoDB, and many more

Log Level

All logging goes to stderr (safe for MCP stdio transport). Control verbosity with:

LOG_LEVEL=debug npx @gnaws/mcp

Available levels: debug, info, warn, error, silent (default: info).

Development

# Build
npm run build

# Dev mode (tsx with hot reload)
npm run dev

# Type-check
npm run typecheck

# Lint
npm run lint

# Test with MCP Inspector
npx @modelcontextprotocol/inspector npx @gnaws/mcp

Contributing

See CONTRIBUTING.md.

Support

If GNAWS saves you money on your AWS bill, consider sponsoring the project.

License

AGPL-3.0 — see LICENSE.

Not affiliated with or endorsed by Amazon Web Services.