{"id":38960343,"url":"https://github.com/ayushgoel24/mcp-netgraph","last_synced_at":"2026-01-17T16:24:10.945Z","repository":{"id":332725471,"uuid":"1133104351","full_name":"ayushgoel24/mcp-netgraph","owner":"ayushgoel24","description":"Model Context Protocol (MCP) server for AWS Network Engineering. Uses NetworkX to build a directed graph of VPC infrastructure (SGs, NACLs, Route Tables), enabling deterministic reachability reasoning and 'shadow path' detection for AI agents.","archived":false,"fork":false,"pushed_at":"2026-01-15T07:26:56.000Z","size":235,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-15T14:20:01.116Z","etag":null,"topics":["agentic-workflow","aws","mcp-server","network-topology","networkx","python3","reachability-analysis","security-engineering","vpc-debugging"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayushgoel24.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-12T22:17:54.000Z","updated_at":"2026-01-15T07:21:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ayushgoel24/mcp-netgraph","commit_stats":null,"previous_names":["ayushgoel24/mcp-netgraph"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ayushgoel24/mcp-netgraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayushgoel24%2Fmcp-netgraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayushgoel24%2Fmcp-netgraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayushgoel24%2Fmcp-netgraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayushgoel24%2Fmcp-netgraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayushgoel24","download_url":"https://codeload.github.com/ayushgoel24/mcp-netgraph/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayushgoel24%2Fmcp-netgraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28511858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflow","aws","mcp-server","network-topology","networkx","python3","reachability-analysis","security-engineering","vpc-debugging"],"created_at":"2026-01-17T16:24:10.863Z","updated_at":"2026-01-17T16:24:10.936Z","avatar_url":"https://github.com/ayushgoel24.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NetGraph\n\n**MCP server for AWS VPC network path analysis and security auditing**\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nNetGraph enables AI assistants to analyze AWS VPC network connectivity by modeling infrastructure as a graph. Ask questions like *\"Can my web server reach the database on port 5432?\"* and get deterministic answers with full path analysis.\n\n## Why NetGraph?\n\n**Without NetGraph**, debugging AWS network connectivity requires:\n- Manually tracing Security Groups, NACLs, and route tables\n- Checking stateful vs stateless rule semantics\n- Verifying return path routing for NACLs\n- Cross-referencing multiple AWS console pages\n\n**With NetGraph**, your AI assistant can:\n- Analyze complete network paths in seconds\n- Identify exactly where traffic is blocked\n- Find resources exposed to the public internet\n- Discover resources by name or tags when you don't have IDs\n\n## Quick Start\n\n### Installation\n\n```bash\npip install aws-vpc-analyzer\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/ayushgoel24/mcp-netgraph.git\ncd mcp-netgraph\npip install -e .\n```\n\nFor detailed setup instructions, see the [Installation Guide](docs/installation.md).\n\n### Configure Your MCP Client\n\nAdd NetGraph to your MCP client configuration. Replace `your-profile` with your AWS CLI profile name.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop\u003c/b\u003e\u003c/summary\u003e\n\n**Config file location:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n**Add this configuration:**\n\n```json\n{\n  \"mcpServers\": {\n    \"netgraph\": {\n      \"command\": \"aws-vpc-analyzer\",\n      \"env\": {\n        \"AWS_PROFILE\": \"your-profile\",\n        \"AWS_REGION\": \"us-east-1\"\n      }\n    }\n  }\n}\n```\n\n**Alternative using uvx (no pip install required):**\n\n```json\n{\n  \"mcpServers\": {\n    \"netgraph\": {\n      \"command\": \"uvx\",\n      \"args\": [\"aws-vpc-analyzer\"],\n      \"env\": {\n        \"AWS_PROFILE\": \"your-profile\",\n        \"AWS_REGION\": \"us-east-1\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code (CLI)\u003c/b\u003e\u003c/summary\u003e\n\n**Config file location:**\n- Global: `~/.claude.json`\n- Project-specific: `.mcp.json` in your project root\n\n**Add this configuration:**\n\n```json\n{\n  \"mcpServers\": {\n    \"netgraph\": {\n      \"command\": \"aws-vpc-analyzer\",\n      \"env\": {\n        \"AWS_PROFILE\": \"your-profile\",\n        \"AWS_REGION\": \"us-east-1\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Code or start a new session.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/summary\u003e\n\nOpen **Settings** → **MCP** and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"netgraph\": {\n      \"command\": \"aws-vpc-analyzer\",\n      \"env\": {\n        \"AWS_PROFILE\": \"your-profile\",\n        \"AWS_REGION\": \"us-east-1\"\n      }\n    }\n  }\n}\n```\n\nRestart Cursor after saving.\n\n\u003c/details\u003e\n\nFor detailed setup instructions including troubleshooting, see the [Installation Guide](docs/installation.md).\n\n### AWS Credentials\n\nNetGraph uses your standard AWS credentials. Ensure you have:\n\n1. **AWS CLI configured** with a profile, or\n2. **Environment variables** set (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`), or\n3. **IAM role** attached (for EC2/Lambda environments)\n\nRequired IAM permissions: [See AWS Permissions](#aws-permissions) | [Full IAM Policy](docs/iam-policy.md)\n\n## Tools\n\n### `analyze_path`\n\nAnalyze network reachability between a source and destination with hop-by-hop evaluation of Security Groups, NACLs, and route tables.\n\n```\nCan instance i-0abc123 reach 10.0.2.50 on port 443?\n```\n\n**Parameters:**\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `source_id` | string | Yes | EC2 instance ID (`i-xxx`) or ENI ID (`eni-xxx`) |\n| `destination_ip` | string | Yes | IPv4 or IPv6 destination address |\n| `port` | integer | Yes | Destination port (1-65535) |\n| `protocol` | string | No | `tcp`, `udp`, `icmp`, or `-1` for all (default: `tcp`) |\n| `force_refresh` | boolean | No | Bypass cache and fetch fresh data (default: `false`) |\n\n**Returns:** Path status (`REACHABLE`, `BLOCKED`, or `UNKNOWN`), hop-by-hop details, and blocking reason if blocked.\n\n---\n\n### `find_public_exposure`\n\nScan a VPC to find resources exposed to the public internet on a specific port.\n\n```\nShow me all resources in vpc-12345678 exposed to SSH on port 22\n```\n\n**Parameters:**\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `vpc_id` | string | Yes | VPC ID to scan (`vpc-xxx`) |\n| `port` | integer | Yes | Port to check for exposure (1-65535) |\n| `protocol` | string | No | `tcp`, `udp`, or `-1` for all (default: `tcp`) |\n| `force_refresh` | boolean | No | Bypass cache (default: `false`) |\n\n**Returns:** List of exposed resources with exposure paths, allowing Security Group rules, and remediation guidance.\n\n---\n\n### `find_resources`\n\nDiscover AWS resources by name pattern or tags. Useful when you know a resource by name but need its ID.\n\n```\nFind all production web servers in vpc-12345678\n```\n\n**Parameters:**\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `vpc_id` | string | Yes | VPC ID to search (`vpc-xxx`) |\n| `tags` | object | No | Tag key-value filters (e.g., `{\"Environment\": \"prod\"}`) |\n| `resource_types` | array | No | Filter by type: `instance`, `eni`, `subnet`, `igw`, `nat`, `peering`, `tgw` |\n| `name_pattern` | string | No | Glob pattern for Name tag (e.g., `web-*`, `*-prod-*`) |\n| `max_results` | integer | No | Maximum results to return (default: 50, max: 50) |\n\n**Returns:** Matching resources with IDs, names, IPs, subnets, and tags.\n\n---\n\n### `list_vpcs`\n\nList and search VPCs in your account. Use this when you need a VPC ID but only know the name or tags.\n\n```\nWhat VPCs do I have? I'm looking for the production one.\n```\n\n**Parameters:**\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `name_pattern` | string | No | Glob pattern for VPC Name tag (e.g., `prod-*`) |\n| `tags` | object | No | Tag key-value filters (e.g., `{\"Environment\": \"production\"}`) |\n| `cidr` | string | No | Filter by CIDR block (e.g., `10.0.0.0/16`) |\n\n**Returns:** List of VPCs with IDs, names, CIDRs, state, and tags.\n\n---\n\n### `refresh_topology`\n\nPre-warm the cache by fetching all resources in specified VPCs. Optional optimization for faster subsequent queries.\n\n```\nPre-load the topology for vpc-12345678\n```\n\n**Parameters:**\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `vpc_ids` | array | Yes | List of VPC IDs to pre-warm (`[\"vpc-xxx\", \"vpc-yyy\"]`) |\n\n**Returns:** Node/edge counts, resources by type, and duration.\n\n---\n\n### `get_cache_stats`\n\nGet cache performance statistics.\n\n**Returns:** Cache hits, misses, hit rate, TTL, and entry counts.\n\n## Configuration\n\nConfigure NetGraph via environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AWS_REGION` | `us-east-1` | AWS region to query |\n| `AWS_PROFILE` | (none) | AWS CLI profile to use |\n| `NETGRAPH_TTL` | `60` | Cache TTL in seconds |\n| `NETGRAPH_ROLE_ARN` | (none) | IAM role ARN for cross-account access |\n| `NETGRAPH_LOG_LEVEL` | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |\n\n## Example Prompts\n\n**Connectivity debugging:**\n\u003e Can my web server i-0abc123 reach the database at 10.0.3.50 on port 5432?\n\n**Security audit:**\n\u003e Find all resources in vpc-prod12345 exposed to the internet on SSH port 22\n\n**Resource discovery:**\n\u003e Find all instances tagged Environment=production in vpc-12345678\n\n**VPC lookup:**\n\u003e List my VPCs - I need to find the one named \"production\"\n\n**Pre-deployment validation:**\n\u003e Verify that i-gateway123 can reach 10.0.2.100 on port 8080\n\nSee [docs/examples.md](docs/examples.md) for more detailed examples.\n\n## How It Works\n\nNetGraph models your VPC as a directed graph:\n\n- **Nodes:** EC2 instances, ENIs, subnets, Internet Gateways, NAT Gateways, VPC Peering connections\n- **Edges:** Routing relationships with CIDR destinations and prefix lengths\n\nWhen you ask about connectivity, NetGraph:\n\n1. **Resolves** the source to its ENI and subnet\n2. **Evaluates** Security Group egress rules (stateful - only checks outbound)\n3. **Evaluates** NACL outbound rules (stateless - must also check return path)\n4. **Traverses** the route table using Longest Prefix Match (LPM)\n5. **Follows** the path through gateways until reaching the destination\n6. **Evaluates** destination NACL inbound and Security Group ingress rules\n7. **Verifies** return path routing to prevent asymmetric routing failures\n\n## AWS Permissions\n\nNetGraph requires read-only EC2 permissions:\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"ec2:DescribeInstances\",\n        \"ec2:DescribeNetworkInterfaces\",\n        \"ec2:DescribeSubnets\",\n        \"ec2:DescribeSecurityGroups\",\n        \"ec2:DescribeNetworkAcls\",\n        \"ec2:DescribeRouteTables\",\n        \"ec2:DescribeInternetGateways\",\n        \"ec2:DescribeNatGateways\",\n        \"ec2:DescribeVpcs\",\n        \"ec2:DescribeVpcPeeringConnections\",\n        \"ec2:DescribeTransitGateways\",\n        \"ec2:DescribeTransitGatewayAttachments\",\n        \"ec2:GetManagedPrefixListEntries\"\n      ],\n      \"Resource\": \"*\"\n    }\n  ]\n}\n```\n\nFor **cross-account analysis**, also add:\n- `sts:AssumeRole` permission\n- Trust relationship on target account roles\n- Set `NETGRAPH_ROLE_ARN` environment variable\n\n## Documentation\n\n- [Installation Guide](docs/installation.md) - Detailed setup instructions\n- [IAM Policy](docs/iam-policy.md) - Copy-paste IAM policies\n- [Examples](docs/examples.md) - Detailed usage examples\n- [Changelog](CHANGELOG.md) - Release notes and version history\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our development process and how to submit pull requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayushgoel24%2Fmcp-netgraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayushgoel24%2Fmcp-netgraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayushgoel24%2Fmcp-netgraph/lists"}