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:
git clone <repository-url>
cd sample-building-mcp-servers-with-python
We recommend using uv to install dependencies as it's faster and more reliable than pip:
# 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:
pip install -r requirements.txt
Usage
Run each server independently:
# 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:
{
"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:
- Create a FastMCP instance
- Define tools using the
@mcp.tool()decorator - Run the server with
mcp.run()
For example, the Calculator Server looks like this:
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
- FastMCP Documentation
- Amazon Q Documentation
- uv Documentation - Recommended Python package manager for FastMCP
Acknowledgments
This project was inspired by 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.