Content
# AWS MCP Server with Agno Agent
This project integrates a set of AWS tools into an MCP (Model Context Protocol) server using [FastMCP](https://github.com/mcp-foundation/mcp) and the [Agno](https://github.com/agno-ai/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](https://ollama.ai/) 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:**
```bash
git clone https://github.com/skjortans/aws-mcp-server.git
cd aws-mcp-server
```
2. **Create a Virtual Environment (optional but recommended):**
```bash
python -m venv venv
source venv/bin/activate # On Windows use: venv\Scripts\activate
```
3. **Install Dependencies:**
If you have a `requirements.txt`, run:
```bash
pip install -r requirements.txt
```
Otherwise, install the dependencies manually:
```bash
pip install boto3 agno fastmcp rich click
```
4. **Install and Start Ollama:**
Follow the [Ollama installation instructions](https://ollama.ai/download) for your platform, then pull a model:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```python
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](LICENSE) file for details.
