sample-building-mcp-servers-with-python

# 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.