An MCP server that lets AI agents scan, analyze, and export AWS resource graphs to find unused resources.
Status: Check whether resources are loaded and see graph size with status.
Scan live AWS: Use scan with an AWS profile to build a resource relationship graph.
Work offline: Use load to load a previously dumped directory without AWS credentials.
List regions: Use regions to see enabled AWS regions from the loaded inventory.
Detect unused resources: Use detect to find orphaned/unused resources (e.g., detached volumes, unassociated IPs).
Export graph: Use export to save the graph as GEXF (Gephi), JSON (sigma.js), or Markdown.
Dump data: Use dump to save raw resource data for later offline analysis.
Agent-friendly: Includes progress notifications, structured errors, and workflow guidance, supporting 81 AWS services.
Allows AI agents to scan AWS accounts, build resource relationship graphs, and detect unused/orphaned resources across 65+ AWS services.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@gnaws/mcp scan my AWS account and find any unused resources"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Related MCP server: mcp-cloudwatch-explorer
npm install -g @gnaws/mcp
# or run without installing:
npx @gnaws/mcpRequires Node.js >= 24.
Add to .kiro/settings/mcp.json:
{
"mcpServers": {
"gnaws": {
"command": "npx",
"args": ["@gnaws/mcp"]
}
}
}Add to claude_desktop_config.json:
{
"mcpServers": {
"gnaws": {
"command": "npx",
"args": ["@gnaws/mcp"]
}
}
}Add to .vscode/mcp.json:
{
"servers": {
"gnaws": {
"command": "npx",
"args": ["@gnaws/mcp"]
}
}
}Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
{
"mcpServers": {
"gnaws": {
"command": "npx",
"args": ["@gnaws/mcp"]
}
}
}Tool | Description | Requires |
| Check server state (loaded? how many nodes/edges?) | — |
| Scan AWS resources live with a profile | AWS credentials |
| Load from a dump directory (offline) | Dump path |
| Find unused/orphaned resources |
|
| Export graph to gexf/json/md/csv |
|
| Save raw data for offline use |
|
| List enabled AWS regions |
|
User: Show me the unused resources in my AWS account
Agent: callsscanwith profile → callsdetect→ presents findings
User: Load the dump from ./data and export a graph
Agent: callsloadwith path → callsexportwith format "gexf"
User: What's the state of the gnaws server?
Agent: callsstatus→ reports no data loaded, suggestsscanorload
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
All logging goes to stderr (safe for MCP stdio transport). Control verbosity with:
LOG_LEVEL=debug npx @gnaws/mcpAvailable levels: debug, info, warn, error, silent (default: info).
# 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/mcpSee CONTRIBUTING.md.
If GNAWS saves you money on your AWS bill, consider sponsoring the project.
AGPL-3.0 — see LICENSE.
Not affiliated with or endorsed by Amazon Web Services.
Detect structurally unused/orphaned resources in the loaded graph. Requires 'scan' or 'load' to be called first. Optionally export findings to a file (.json or .md).
| Name | Required | Description | Default |
|---|---|---|---|
| outputPath | No | Optional path to write findings (.json or .md). If omitted, returns findings as text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since there are no annotations, the description fully carries the behavioral burden. It discloses that the tool operates on a 'loaded graph', requires prior commands, and optionally exports to file. It does not describe error behavior or performance characteristics, but for a detection tool these are reasonable gaps. The file format details (.json or .md) are a nice touch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. The prerequisite condition is front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple detection tool with one optional parameter and no output schema, the description is nearly complete. It covers purpose, prerequisite, and output format. It could mention what happens if the graph is empty or what 'unused/orphaned' means exactly, but the title helps clarify.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one well-described parameter. The description reiterates the purpose of outputPath (optional export vs. returning text). This matches the schema, so baseline 3 is appropriate. No additional semantic nuance beyond the schema is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Detect Unused Resources' combined with description 'Detect structurally unused/orphaned resources in the loaded graph' provides a specific verb–resource pair. It clearly states the scope (loaded graph) and distinguishes from siblings like 'scan' (which loads data) and 'export' (which exports already-known data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a prerequisite: 'Requires scan or load to be called first.' This tells the agent when not to use this tool. However, it does not mention alternatives or when to choose this over checking resource status via 'status' or 'regions', leaving a slight gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dump loaded resources to a directory for offline use. Requires 'scan' or 'load' to be called first. The output can later be used with 'load' for offline analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Output directory path. Defaults to 'dump'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It clarifies that the tool writes to a directory, requires a prerequisite step, and produces output consumable by 'load'. While it doesn't detail disk space or error handling, the core behavioral traits are well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the core action, and includes essential usage context. Every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 optional param, no nested objects, no output schema) and no annotations, the description is complete. It explains prerequisites, output usage, and default behavior, leaving no major gaps for an agent to misunderstand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that 'path' is the output directory path with a default of 'dump', which is not fully detailed in the schema's description. The schema says 'Output directory path. Defaults to 'dump'.' which is already clear, so the description doesn't add much extra meaning beyond the schema, but the schema itself is already good.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to dump loaded resources to a directory for offline use. It uses a specific verb 'dump' and resource 'loaded resources', and distinguishes itself from siblings by referencing 'scan' or 'load' as prerequisites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: after 'scan' or 'load' has been called. It also explains the downstream use case ('offline analysis' with 'load'), effectively preventing misuse and clarifying the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the resource graph to a file. Requires 'scan' or 'load' to be called first. Supported formats: gexf (Gephi), json (sigma.js viewer), md (markdown report), csv (flat inventory sheet).
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Output file path. Defaults to graph.gexf, graph.json, report.md, or inventory.csv | |
| format | Yes | Export format: 'gexf' for Gephi, 'json' for sigma.js viewer, 'md' for markdown report, 'csv' for a flat inventory sheet |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the prerequisite and supported formats, but doesn't mention side effects like file overwriting or whether the operation is reversible. For an export tool, the write nature is implied, but more detail on behavior (e.g., overwriting, error conditions) would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The purpose and prerequisite are front-loaded, and the format list is compact and informative. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only 2 parameters, a clear prerequisite, and no output schema, the description covers the essential context. It explains the formats and the need for prior scanning/loading. Minor gaps like return behavior or error handling are not critical given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by mapping each format to its intended viewer (e.g., gexf for Gephi, json for sigma.js), which goes beyond the schema's descriptions and helps the agent choose the right format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Export' with the resource 'resource graph' and the output to a file, and lists specific formats. It distinguishes itself from siblings like 'detect', 'scan', 'load' by focusing on output, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a prerequisite ('Requires scan or load to be called first'), which is key usage guidance. It doesn't explicitly mention when not to use it or alternative tools, but the prerequisite provides clear context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load resources from a previously dumped directory (offline mode). No AWS credentials needed. After loading, use 'regions', 'detect', or 'export' to work with the data.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to a gnaws dump directory containing manifest.json and resource files |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries a heavier burden. It usefully discloses that no AWS credentials are needed. However, it does not mention side effects (e.g., whether loading overwrites previous state), error handling, or what happens if the path is invalid. The description adds some value but falls short of full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: purpose, key behavior (no credentials), and follow-up guidance. No redundancy, each sentence adds distinct value. Perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter and no output schema, the description addresses the tool's purpose, offline context, and post-load workflow. It lacks detail on return values or error conditions, but for a simple data-loading tool the coverage is mostly sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the only parameter 'path' is fully described in the schema). The description adds no additional parameter-level detail beyond what the schema already provides. Baseline 3 is appropriate given the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('load') and resource ('cached resources from a previously dumped directory'), clearly distinguishing from sibling tools like 'scan' (live scanning) and 'dump' (creating dumps). It explicitly mentions offline mode, which differentiates it from live operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'No AWS credentials needed' and suggests subsequent tools ('regions', 'detect', 'export'). It implies use when a dump directory exists, but doesn't explicitly state when NOT to use it or list alternatives for equivalent functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List enabled AWS regions from the loaded inventory. Requires 'scan' or 'load' to be called first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the operation is a list of enabled regions and requires a prior call. It does not describe what happens if the inventory is not loaded (e.g., error behavior), nor does it mention any other traits like idempotency, rate limits, or whether the output is a simple list of region names. For a tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence front-loads the core purpose, and the second immediately provides the critical prerequisite. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should explain return values. It states 'List enabled AWS regions' but does not describe the format of the output (e.g., list of region names, objects, or something else). It also does not mention error conditions or edge cases. Given the tool's simplicity, the missing output description is a gap, but the prerequisite and purpose are covered, making it minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the input schema is trivially fully covered. The description does not need to add parameter semantics because none exist. According to the rules, 0 params gives a baseline of 4, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb and resource: 'List enabled AWS regions from the loaded inventory.' This explicitly distinguishes it from siblings like 'scan' (data ingestion), 'load' (data loading), and 'export' (data output), as it is a read-only retrieval operation on already-loaded data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite: 'Requires "scan" or "load" to be called first.' This tells the agent when to use the tool (after data loading) and implicitly not to use it before. However, it does not mention alternatives or when-not scenarios beyond the prerequisite, which keeps it from being a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan AWS resources live using an AWS profile. This builds an in-memory graph of all resources and their relationships. This is a long-running operation (may take several minutes). After scanning, use 'regions' to list regions, 'detect' to find unused resources, 'export' to export the graph, or 'dump' to save raw data for offline use.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | Yes | AWS profile name from ~/.aws/credentials (e.g., 'default', 'production') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden for behavioral disclosure. It notes the operation is live and long-running, builds an in-memory graph, and hints at the data's ephemeral nature. It could mention if it modifies anything or requires specific permissions, but for a scan tool, this is strong coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The two sentences are informative and efficient, with no wasted words. The first sentence states the core purpose, and the second provides usage timing and lists sibling tools for subsequent steps. Perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema (one flat param, no output schema), the description covers the essential context: what it does, that it's long-running, and what tools to use next. It could mention failure modes (e.g., invalid profile) but is sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, so the description doesn't need to repeat parameter details. The description adds context by mentioning 'AWS profile' without duplicating schema info. Baseline 3 is appropriate as the schema fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Scan AWS resources live using an AWS profile' and explains it builds an in-memory graph. It distinguishes itself from siblings by explicitly listing what to do after scanning (regions, detect, export, dump), showing it's the initial data-gathering step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says this is a 'long-running operation (may take several minutes)', setting expectations. It tells the agent to use this first, then lists sibling tools for post-scan actions, providing clear when-to-use and next-step guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the current state of the gnaws server: whether resources are loaded, graph size, and available actions. Call this first to understand what tools are available.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses it reports server state including resources, graph size, and available actions. No mention of return format, latency, or whether state could change between calls, but the read-only nature is implicitly clear. Reasonably transparent for a simple status tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, succinct and front-loaded with purpose, then usage advice. Every sentence adds value with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple zero-parameter status check with sibling context like 'scan' and 'load', the description fully covers what the agent needs to decide to call it first. No output schema exists but the description lists what will be returned (resource load state, graph size, actions).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters to document, schema coverage is 100%. Description adds no parameter info but also has no parameters needing explanation. Baseline 3 for no parameters applies; a slight bonus for mentioning what the tool checks (graph size, resources) which adds meaning beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb ('check') with a concrete resource (the server state: resources loaded, graph size, available actions). Clearly distinguishes itself from siblings like 'scan' or 'load' by establishing this as the initial status/introspection tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises calling this tool first to understand what tools are available, providing clear when-to-use guidance. Absence of when-not-to is acceptable given this is a no-parameter status check with no destructive side effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0export3 fields changedInput schema / properties / format / descriptionPrevious value: -"Export format: 'gexf' for Gephi, 'json' for sigma.js viewer, 'md' for markdown report"New value: +"Export format: 'gexf' for Gephi, 'json' for sigma.js viewer, 'md' for markdown report, 'csv' for a flat inventory sheet"Input schema / properties / format / enumPrevious value: -[
- "gexf",
- "json",
- "md"
-]New value: +[
+ "gexf",
+ "json",
+ "md",
+ "csv"
+]Input schema / properties / path / descriptionPrevious value: -"Output file path. Defaults to graph.gexf, graph.json, or report.md"New value: +"Output file path. Defaults to graph.gexf, graph.json, report.md, or inventory.csv"v0.1.0detectdumpexportloadregionsscanstatusScored across 7 tools
Each tool maps to a distinct action (scan live, load offline, detect orphans, export graph, dump raw data, list regions, show status), but export and dump both involve saving data and detect can also write findings to a file, creating mild overlap. Overall boundaries are clear enough for an agent to select correctly.
All tool names are single lowercase words following a simple command-style convention (scan, load, detect, export, dump, status). The only non-verb, regions, still fits the same flat lowercase pattern, so there is no style mixing.
Seven tools is well-scoped for an AWS resource graph scanning and orphan detection server. Each tool supports a distinct stage in the workflow without redundancy or bloat.
The core workflow is complete: scan or load builds the graph, status confirms readiness, regions summarizes scope, detect finds orphans, dump enables offline reuse, and export produces output. A minor gap is the lack of a direct resource-listing/query tool, though export formats can serve that purpose.
Give AI agents identity, scoped access, trusted context, and verifiable actions through MCP.
Let AI agents query data and act across all your business apps via MCP.
Verified AI free tiers plus source-backed agent and MCP discovery monitoring.
Compliance frameworks (SOC 2, ISO 27001, CMMC, NIST, more) delivered to AI agents as MCP tools.
