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:

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:

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.