AWS MCP Server with Agno Agent

This project integrates a set of AWS tools into an MCP (Model Context Protocol) server using FastMCP and the Agno framework. The server exposes AWS functionalities such as listing security groups, listing S3 buckets, and analyzing VPC connections, enabling remote clients to interact with them via the standardized MCP.

This was a demo for the aws meetup. Mostly a demo of what you can do with mcp and local agents.

Features

• AWS Security Group Tool: Lists AWS security groups with details on inbound and outbound rules.
• AWS S3 Bucket Tool: Lists S3 buckets with region, creation date, and access policy information.
• AWS VPC Connections Tool: Analyzes VPC connections, including peering, endpoints, transit gateways, route tables, and network ACLs.
• MCP Server: Exposes the above tools over a network endpoint, allowing invocation by any MCP-compliant client.
• Interactive Agno Agent: A sophisticated agent with task management, command history, and real-time tool call streaming.
• Ollama Integration: Uses local Ollama models for AI capabilities, reducing dependency on external APIs.

Prerequisites

• Python 3.11 or later
• AWS credentials configured for boto3 (either via environment variables or AWS config/credentials file)
• Ollama installed and running locally (for the agent component)
• Required Python packages:
  • boto3
  • agno
  • fastmcp (for the server component)
  • rich (for the interactive console)

Installation

1. Clone the Repository:

   hljs language-bash

   Copy

   git clone https://github.com/skjortans/aws-mcp-server.git
   cd aws-mcp-server
   

2. Create a Virtual Environment (optional but recommended):

   hljs language-bash

   Copy

   python -m venv venv
   source venv/bin/activate  # On Windows use: venv\Scripts\activate
   

3. Install Dependencies:

   If you have a requirements.txt, run:

   hljs language-bash

   Copy

   pip install -r requirements.txt
   

   Otherwise, install the dependencies manually:

   hljs language-bash

   Copy

   pip install boto3 agno fastmcp rich click
   

4. Install and Start Ollama:

   Follow the Ollama installation instructions for your platform, then pull a model:

   hljs language-bash

   Copy

   ollama pull qwen3  # or another model of your choice
   

Usage

Running the MCP Server

The main script wraps the AWS tools into a FastMCP server and starts it with SSE transport. To run the server, execute:

python src/aws-security-mcp-server.py

Upon running, you should see:

[MCP Server] Listening on 127.0.0.1:5678 (TCP transport)

Note: While the message mentions TCP transport, the server is configured to use SSE transport in the code.

The server processes incoming MCP requests by dispatching them to the appropriate AWS tool.

Running the Interactive Agent

The project includes a sample interactive agent that connects to the MCP server. To run the agent, execute:

python src/aws-demo-agent.py

This will start an interactive console where you can:

• Run queries that execute in the background
• Manage multiple concurrent tasks
• View real-time tool call streaming
• Access command history and help

Example commands:

red-team> list_security_groups us-east-1
red-team> list_s3_buckets
red-team> analyze_vpc_connections us-east-1
red-team> tasks  # List all running tasks
red-team> help   # Show help information

Using the Simple Agent

For a simpler implementation, you can use the basic agent:

python src/aws-agent.py

Connecting with Custom Clients

You can also connect to the MCP server using any MCP-compliant client. For example, using Agno's MCPTools:

from agno.agent import Agent
from agno.tools.mcp import MCPTools
from agno.models.ollama import Ollama

# Connect to the MCP server
mcp_tools = MCPTools(url="http://127.0.0.1:8000/sse/", transport='sse')  # Adjust URL as needed for your setup

# Create an agent with the MCP tools
model = Ollama(id="qwen3")
agent = Agent(
    model=model,
    tools=[mcp_tools],
    instructions="You are an AWS security expert."
)

# Run a query
result = agent.run("What VPC connections do I have?")
print(result)

Ensure that the MCP server is running before executing the client code.

Project Structure

aws-mcp-server/
├── README.md
├── requirements.txt  # List of dependencies
├── src/
│   ├── aws-security-mcp-server.py  # MCP server implementation with AWS tools
│   ├── aws-demo-agent.py           # Interactive Agno agent with task management
│   └── aws-agent.py                # Simple agent implementation

Contributing

Contributions are welcome! If you have suggestions or improvements:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Submit a pull request with a detailed explanation of your changes.

Architecture

MCP Server

The MCP server is built using FastMCP and exposes AWS tools as MCP-compatible endpoints. It uses Server-Sent Events (SSE) transport for real-time communication with clients.

Agent Architecture

The project includes two agent implementations:

1. Interactive Agno Agent (aws-demo-agent.py):

   • Built on the Agno framework
   • Uses local Ollama models for AI capabilities
   • Features a non-blocking interactive console with rich formatting
   • Supports parallel task execution and management
   • Provides real-time streaming of tool calls and responses
   • Includes command history and help functionality

2. Simple Agent (aws-agent.py):

   • Uses the smolagents library
   • Simpler implementation for basic use cases
   • Connects to the MCP server to access AWS tools
   • Note: This implementation is missing the import for MCPClientParameters and may need to be updated

License

Free for all!

This project is licensed under the MIT License – see the LICENSE file for details.