regdamon25/python-mcp-server-template

{{PROJECT_NAME}}

{{PROJECT_DESCRIPTION}}

This is an MCP (Model Context Protocol) server template that provides AI agents access to your API endpoints. It's built with Python and can be run using uv package manager or Docker.

Setup

Prerequisites

• Python 3.13 or higher (latest stable)
• uv package manager (or Docker)

Method 1: Local Development with uv

1. Install uv (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Install dependencies:

   uv sync
   

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your API configuration
   

4. Run the server:

   uv run python -m src.server
   

Method 2: Docker

1. Configure environment variables:

   cp .env.example .env
   # Edit .env with your API configuration
   

2. Build and run with Docker Compose:

   docker-compose up --build
   

   Or build and run manually:

   docker build -t my-mcp-server .
   docker run --rm -it --env-file .env my-mcp-server
   

Available Tools

• get_users: Retrieve users from the API
• create_user: Create a new user
• get_user_by_id: Get user by ID

Configuration

Set these environment variables in your .env file:

• API_BASE_URL: Base URL of your existing API (default: http://localhost:8000)
• API_KEY: API authentication key (optional)

Docker-specific Notes

• The default API_BASE_URL in Docker is set to http://host.docker.internal:8000 to access services on the host machine
• Adjust the docker-compose.yml file if you need to expose ports or use different networking

Connecting to AI Clients

To connect this MCP server to an AI client like Claude Desktop, add this configuration:

Local Development

{
  "mcpServers": {
    "{{PROJECT_NAME}}": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.server"],
      "cwd": "/path/to/{{PROJECT_NAME}}"
    }
  }
}

Docker

{
  "mcpServers": {
    "{{PROJECT_NAME}}": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/path/to/{{PROJECT_NAME}}/.env", "{{PROJECT_NAME}}"],
      "cwd": "/path/to/{{PROJECT_NAME}}"
    }
  }
}

Development

Testing

# Run tests with uv
uv run pytest

# Or create a simple test
uv run python test_server.py

Customization

To adapt this for your specific API:

1. Update src/tools.py:

   • Replace the example tools with your actual API endpoints
   • Modify the APIClient.make_request() method if you need custom authentication
   • Update the handle_tool_call() function with your endpoint logic

2. Update src/config.py:

   • Add any additional configuration your API needs
   • Modify authentication settings

3. Add more sophisticated error handling:

   • Handle specific HTTP status codes
   • Add retry logic for transient failures
   • Implement proper logging

Project Structure

{{PROJECT_NAME}}/
├── src/
│   ├── __init__.py
│   ├── server.py          # Main MCP server implementation
│   ├── tools.py           # Tool definitions and API client
│   └── config.py          # Configuration management
├── pyproject.toml         # Project configuration and dependencies
├── docker-compose.yml     # Docker Compose configuration
├── Dockerfile             # Docker image definition
├── .env.example          # Example environment variables
├── .gitignore            # Git ignore patterns
├── .dockerignore         # Docker ignore patterns
└── README.md             # This file