<div align="center">

🚀 MCP Server

Production-Ready Model Context Protocol Server Built with Python & FastMCP

<p align="center">

A clean, modular, scalable, and Docker-ready implementation of the Model Context Protocol (MCP), designed for AI applications and developer productivity.

</p>

<p align="center">

<img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white"/>

<img src="https://img.shields.io/badge/FastMCP-Latest-009688?style=for-the-badge"/>

<img src="https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker&logoColor=white"/>

<img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge"/>

<img src="https://img.shields.io/badge/Status-Production%20Ready-success?style=for-the-badge"/>

</p>

<p align="center">

<img src="https://img.shields.io/github/stars/golam74/MCP_SERVER?style=social"/>

<img src="https://img.shields.io/github/forks/golam74/MCP_SERVER?style=social"/>

<img src="https://img.shields.io/github/watchers/golam74/MCP_SERVER?style=social"/>

</p>

</div>

---

📑 Table of Contents

• 📖 Overview
• ✨ Features
• 🏗 Architecture
• 📂 Project Structure
• 🛠 Tech Stack
• 🚀 Getting Started
• 🐳 Docker
• ⚙ Configuration
• 🧩 Available Tools
• 📜 Logging
• 📊 Roadmap
• 🤝 Contributing
• 📄 License

---

📖 Overview

The MCP Server is a production-ready implementation of the Model Context Protocol (MCP) using Python and FastMCP.

This project demonstrates how to build scalable, modular, and maintainable MCP servers that can expose reusable tools for AI assistants and MCP-compatible clients.

Unlike simple examples, this repository follows a production-oriented architecture with centralized tool registration, structured logging, Docker support, and a clean project layout.

It serves as both:

• 📚 A learning resource for developers exploring MCP.
• 🏗 A solid foundation for building real-world AI tool servers.

---

✨ Features

Feature	Status
FastMCP Server	✅
Modular Architecture	✅
Central Tool Registry	✅
Professional Logging	✅
Tool Execution Logs	✅
Docker Support	✅
Docker Compose	✅
Environment Configuration	✅
Easy Tool Registration	✅
Production Ready Structure	✅
Extensible Design	✅

---

🎯 Why This Project?

Most MCP examples available online are intentionally minimal.

This project goes beyond the basics by demonstrating:

• Clean architecture
• Separation of concerns
• Modular tool development
• Production-grade logging
• Dockerized deployment
• Reusable project structure
• Scalable code organization

It is intended to be a strong starting point for developers building AI-powered applications with MCP.

---

🏗 Architecture

The project follows a modular architecture to keep the codebase clean, maintainable, and easy to extend.

flowchart TD

    Client["MCP Client"]
    Server["FastMCP Server"]
    Registry["Tool Registry"]
    Calculator["Calculator Tools"]
    Time["Time Tools"]
    File["File Tools"]
    System["System Tools"]
    Math["Math Tools"]
    Text["Text Tools"]
    Utility["Utility Tools"]
    Logger["Logging System"]
    Logs["Log Files"]

    Client --> Server
    Server --> Registry

    Registry --> Calculator
    Registry --> Time
    Registry --> File
    Registry --> System
    Registry --> Math
    Registry --> Text
    Registry --> Utility

    Calculator --> Logger
    Time --> Logger
    File --> Logger
    System --> Logger
    Math --> Logger
    Text --> Logger
    Utility --> Logger

    Logger --> Logs

---

📂 Project Structure

MCP_SERVER/
│
├── .github/
│   └── workflows/
│       └── ci.yml
│
├── app/
│   ├── tools/
│   │   ├── math_tool.py
│   │   ├── text_tools.py
│   │   └── utility_tools.py
│   │
│   ├── calculator.py
│   ├── datetime_tool.py
│   ├── file_reader.py
│   ├── logger.py
│   ├── log_decorator.py
│   ├── registry.py
│   ├── system_info.py
│   └── time_tool.py
│
├── logs/
│   ├── error.log
│   └── mcp.log
│
├── .dockerignore
├── .env
├── .gitignore
├── CHANGELOG.md
├── config.py
├── CONTRIBUTING.md
├── docker-compose.yml
├── Dockerfile
├── LICENSE
├── pyproject.toml
├── pytest.ini
├── README.md
├── requirements.txt
└── server.py

---

⚙ Project Workflow

Start Server
      │
      ▼
Create FastMCP Instance
      │
      ▼
Register All Tools
      │
      ▼
Wait For MCP Client
      │
      ▼
Receive Tool Request
      │
      ▼
Execute Tool
      │
      ▼
Write Logs
      │
      ▼
Return Response

---

🛠 Tech Stack

Technology	Purpose
🐍 Python 3.11+	Programming Language
⚡ FastMCP	MCP Framework
🤖 Model Context Protocol	AI Tool Communication
🐳 Docker	Containerization
📦 Docker Compose	Local Deployment
📝 Logging	Monitoring & Debugging
⚙ python-dotenv	Environment Variables
🧪 Pytest	Future Testing
🔄 GitHub Actions	Future CI/CD

---

🎯 Design Principles

The project is built around a few core engineering principles:

• Modular architecture
• Single Responsibility Principle (SRP)
• Separation of Concerns
• Easy extensibility
• Centralized tool registration
• Consistent logging
• Docker-first deployment
• Clean project organization

---

📁 Core Modules

Module	Responsibility
server.py	Starts the MCP server
registry.py	Registers all available tools
logger.py	Configures application logging
log_decorator.py	Logs tool execution automatically
config.py	Central application configuration
calculator.py	Calculator-related tools
time_tool.py	Time and date utilities
file_reader.py	File reading tools
system_info.py	System information tools
app/tools/	Additional utility modules

---

🚀 Request Lifecycle

MCP Client
     │
     ▼
FastMCP Server
     │
     ▼
Registry
     │
     ▼
Requested Tool
     │
     ▼
Execute Function
     │
     ▼
Log Request
     │
     ▼
Return Result

---

📌 Key Advantages

• Clean folder structure
• Easy to maintain
• Easy to test
• Easy to extend
• Production-ready layout
• Reusable architecture
• Docker support
• Consistent logging
• Beginner friendly
• Open-source friendly

---

🚀 Getting Started

Follow the steps below to set up the project on your local machine.

---

📋 Prerequisites

Before running the project, ensure the following software is installed:

Software	Version
Python	3.11+
Git	Latest
Docker (Optional)	Latest
Docker Compose (Optional)	Latest

Verify your installation:

python --version
git --version
docker --version

---

📥 Clone the Repository

git clone https://github.com/golam74/MCP_SERVER.git

Navigate to the project directory:

cd MCP_SERVER

---

🐍 Create a Virtual Environment

Windows

python -m venv venv

Activate it:

venv\Scripts\activate

Linux / macOS

python3 -m venv venv

Activate it:

source venv/bin/activate

---

📦 Install Dependencies

Upgrade pip:

python -m pip install --upgrade pip

Install project dependencies:

pip install -r requirements.txt

---

⚙ Environment Variables

Create a .env file in the project root.

Example:

APP_NAME=MCP Server
LOG_LEVEL=INFO

You can add additional configuration values as your project grows.

---

▶ Run the Server

Start the MCP server:

python server.py

Expected output:

============================================================
MCP Server started successfully.
============================================================

---

🐳 Docker Support

Build the Docker image:

docker build -t mcp-server .

Run the container:

docker run --rm mcp-server

---

🐳 Docker Compose

Start the project:

docker compose up --build

Stop the project:

docker compose down

---

✅ Verify Installation

Everything is configured correctly if:

• ✅ Virtual environment is activated
• ✅ Dependencies install successfully
• ✅ Server starts without errors
• ✅ Log files are created
• ✅ Docker image builds successfully
• ✅ Docker Compose starts correctly

---

📄 Configuration Files

File	Description
server.py	Application entry point
config.py	Application configuration
.env	Environment variables
requirements.txt	Python dependencies
Dockerfile	Docker image
docker-compose.yml	Docker Compose configuration
README.md	Project documentation

---

📝 Logging

The server automatically creates log files inside the logs/ directory.

logs/
├── mcp.log
└── error.log

Each tool execution is logged with:

• Timestamp
• Tool Name
• Arguments
• Result
• Exceptions (if any)

Example:

2026-07-18 05:38:43 | INFO | Tool Started : add_numbers
2026-07-18 05:38:43 | INFO | Arguments : (10, 20)
2026-07-18 05:38:43 | INFO | Result : 30
2026-07-18 05:38:43 | INFO | Tool Finished : add_numbers

---

🧩 Available MCP Tools

The server is organized into independent tool modules, making it easy to maintain and extend.

Category	Description
➕ Calculator Tools	Basic arithmetic operations
🕒 Time Tools	Current date and time utilities
📄 File Reader	Read text files safely
💻 System Information	Operating system and hardware details
🔢 Math Tools	Advanced mathematical utilities
📝 Text Tools	String manipulation and formatting
⚙ Utility Tools	General-purpose helper utilities

---

🚀 Adding a New Tool

Adding a new tool to the server requires only three simple steps.

Step 1

Create your tool inside the appropriate module.

Example:

@mcp.tool
def square(number: int) -> int:
    return number * number

---

Step 2

Register the tool inside the module.

def register_math_tools(mcp):
    ...

---

Step 3

Import the registration function into:

app/registry.py

and register it:

register_math_tools(mcp)

That's it!

No changes are required in server.py.

---

💻 Example Usage

Calculator

add_numbers(10, 20)

# Output
30

---

Time Tool

get_current_time()

Output

10:45:23

---

File Reader

read_file("example.txt")

Output

Hello World

---

System Information

get_system_info()

Example Output

Operating System : Windows
Python Version   : 3.11
Machine          : AMD64

---

📜 Logging

Every tool execution is automatically logged.

Logged information includes:

• Tool Name
• Arguments
• Return Value
• Exceptions
• Timestamp

Example

2026-07-18 05:38:43 | INFO | Tool Started : add_numbers
2026-07-18 05:38:43 | INFO | Arguments : (10, 20)
2026-07-18 05:38:43 | INFO | Result : 30
2026-07-18 05:38:43 | INFO | Tool Finished : add_numbers

---

📊 Project Status

Feature	Status
FastMCP Server	✅
Tool Registry	✅
Professional Logging	✅
Docker Support	✅
Docker Compose	✅
Environment Configuration	✅
Modular Architecture	✅
GitHub Repository	✅
Unit Tests	🚧
GitHub Actions	🚧

---

🗺 Roadmap

Version 1.0

• [x] FastMCP Server
• [x] Tool Registration System
• [x] Modular Architecture
• [x] Logging System
• [x] Docker Support
• [x] Docker Compose

---

Version 1.1

• [ ] Unit Testing
• [ ] GitHub Actions
• [ ] Code Coverage
• [ ] Better Error Handling

---

Version 1.2

• [ ] Async Tools
• [ ] More Utility Tools
• [ ] Performance Optimization

---

Version 2.0

• [ ] Authentication
• [ ] Database Support
• [ ] Monitoring Dashboard
• [ ] Plugin Architecture

---

🤝 Contributing

Contributions are always welcome!

If you'd like to improve this project, please follow these steps:

1. Fork the repository.
2. Create a new feature branch.

git checkout -b feature/awesome-feature

3. Commit your changes.

git commit -m "Add awesome feature"

4. Push your branch.

git push origin feature/awesome-feature

5. Open a Pull Request.

Please make sure your code follows the existing project structure and coding style.

---

🧪 Future Improvements

The following features are planned for future releases:

• Async MCP Tools
• Unit & Integration Tests
• GitHub Actions (CI/CD)
• Code Coverage Reports
• Performance Benchmarking
• Authentication & Authorization
• Database Integration
• Plugin Architecture
• Monitoring Dashboard
• API Documentation

---

📈 Project Goals

This repository is designed to serve as:

• 📚 A learning resource for developers exploring MCP.
• 🏗 A production-ready starter template.
• 🤖 A foundation for AI tool development.
• 🚀 A portfolio-quality open-source project.

---

🤝 Support

If you find this project useful:

• ⭐ Star the repository
• 🍴 Fork the project
• 🐛 Report bugs
• 💡 Suggest new features
• 🔥 Contribute improvements

Your support helps make the project better for everyone.

---

📄 License

This project is licensed under the MIT License.

See the LICENSE file for more details.

---

👨‍💻 Author

Golam Israil

AI Engineer | Python Developer | AI Automation Enthusiast

Connect with Me

• GitHub: https://github.com/golam74
• LinkedIn: (Add your LinkedIn profile here)

---

🙏 Acknowledgements

Special thanks to the amazing open-source community and the technologies that made this project possible.

• Python
• FastMCP
• Model Context Protocol (MCP)
• Docker
• GitHub
• Open Source Community

---

🌟 If You Like This Project

If this repository helped you learn something new or saved you time:

⭐ Give it a Star

🍴 Fork it

📢 Share it with others

Every contribution and every star motivates further development.

---

<div align="center">

🚀 Happy Coding!

Build • Learn • Share • Grow

Made with ❤️ by Golam Israil

</div>