README.md•4.81 kB
# MCP Sample
A Python implementation of Model Context Protocol (MCP) servers for extending AI assistant capabilities.
## Overview
This project provides sample MCP servers that can be used with Amazon Q or other MCP-compatible AI assistants. The servers implement various functionalities:
- **Calculator Server**: Performs basic arithmetic operations
- **RDS Server**: Interacts with Amazon RDS instances
- **S3 Server**: Manages Amazon S3 buckets and objects
- **PostgreSQL Server**: Connects to PostgreSQL databases and executes queries
These servers demonstrate how to build MCP servers in Python using the FastMCP framework, which provides a high-level, Pythonic interface for implementing the Model Context Protocol.
## Prerequisites
- Python 3.12+
- FastMCP library
- uv (recommended Python package manager for FastMCP)
- AWS credentials configured for RDS and S3 operations (for the respective servers)
- An MCP-compatible AI assistant (like Amazon Q)
## Installation
Clone the repository and install the dependencies:
```bash
git clone <repository-url>
cd sample-building-mcp-servers-with-python
```
We recommend using [uv](https://github.com/astral-sh/uv) to install dependencies as it's faster and more reliable than pip:
```bash
# Install uv if you don't have it
curl -sSf https://install.python-poetry.org | python3 -
# Install dependencies with uv
uv pip install -r requirements.txt
```
Alternatively, you can use pip:
```bash
pip install -r requirements.txt
```
## Usage
Run each server independently:
```bash
# Run the calculator server
python src/calculator_server.py
# Run the RDS server
python src/rds_server.py
# Run the S3 server
python src/s3_server.py
# Run the PostgreSQL server (requires a connection string)
python src/postgresql_server.py "postgresql://username:password@hostname:port/database"
```
### Integration with Amazon Q CLI
To integrate these MCP servers with Amazon Q CLI or other MCP-compatible clients, add a configuration like this to your `.amazon-q.json` file:
```json
{
"mcpServers": {
"calculator": {
"command": "python /path/to/sample-building-mcp-servers-with-python/src/calculator_server.py",
"args": []
},
"s3": {
"command": "python /path/to/sample-building-mcp-servers-with-python/src/s3_server.py",
"args": []
},
"rds": {
"command": "python /path/to/sample-building-mcp-servers-with-python/src/rds_server.py",
"args": []
},
"postgres": {
"command": "python /path/to/sample-building-mcp-servers-with-python/src/postgresql_server.py",
"args": ["postgresql://username:password@hostname:port/database"]
}
}
}
```
Replace `/path/to/sample-building-mcp-servers-with-python/` with the actual path to your project. Once configured, Amazon Q will be able to use these servers to extend its capabilities.
## Server Descriptions
### Calculator Server
Provides basic arithmetic operations like addition, subtraction, multiplication, and division.
### RDS Server
Lists and manages Amazon RDS instances in specified regions.
### S3 Server
Manages S3 buckets and objects, including listing buckets by region.
### PostgreSQL Server
Connects to PostgreSQL databases and executes read-only queries, lists tables, and provides schema information.
## Understanding the Code
Each server follows a similar pattern:
1. Create a FastMCP instance
2. Define tools using the `@mcp.tool()` decorator
3. Run the server with `mcp.run()`
For example, the Calculator Server looks like this:
```python
from fastmcp import FastMCP
from typing import Annotated
from pydantic import Field
mcp = FastMCP("Calculator Server")
@mcp.tool()
def sum(
a: Annotated[int, Field(description="The first number")],
b: Annotated[int, Field(description="The second number")]
) -> int:
"""Calculate the sum of two numbers"""
return a + b
if __name__ == "__main__":
mcp.run()
```
## Dependencies
- FastMCP: Python implementation of the Model Context Protocol
- boto3: AWS SDK for Python (for S3 and RDS servers)
- asyncpg: PostgreSQL client library (for PostgreSQL server)
- pydantic: Data validation and settings management
## Learning More
To learn more about the Model Context Protocol and FastMCP:
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP Documentation](https://gofastmcp.com/)
- [Amazon Q Documentation](https://docs.aws.amazon.com/amazonq/)
- [uv Documentation](https://github.com/astral-sh/uv) - Recommended Python package manager for FastMCP
## Acknowledgments
This project was inspired by [sample-building-mcp-servers-with-rust](https://github.com/aws-samples/sample-building-mcp-servers-with-rust), which provides a similar implementation of MCP servers using Rust. We thank the authors for their work and inspiration.