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.

Related MCP server: MCP Server Python Template

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.