Random Number

You have a Python MCP server that generates random numbers using weather-derived seeds. It exposes a lightweight local interface you can drive from any MCP client, making it easy to obtain reproducible randomness tied to weather data without exposing complex internals.

How to use

Start the MCP server locally using the runtime tool and the path to your project. Once the server is running, you can request random numbers from your MCP client by targeting the weather MCP server name. The server is designed to be straightforward to use from standard MCP clients, handling seed generation from weather data behind the scenes and returning random values for your applications. You can run multiple requests in parallel, and the server will manage concurrency while maintaining deterministic behavior for a given seed.

How to install

#!/bin/bash

# Prerequisites
# 1) Install the UV runtime (if not already installed)
#    The install script is provided by the UV project.
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2) Prepare your working directory and project
#    Place this code base at /ABSOLUTE/PATH/TO/PARENT/FOLDER/random-number-server

# Install dependencies and initialize the project for development
uv sync

# Install in editable mode for development
uv pip install -e .

# Optional: Run a quick local check (unit tests)
uv run pytest -q

# If you plan to build a Docker image, see the Docker build steps below.

Additional sections

Note any local configuration needed by your MCP client to connect to the weather MCP server. The server does not require a networked API to be up if you are running in-process with the client, but for cross-process usage ensure your client's MCP target is configured to the weather server.

Build and docker options

# Docker image build (base: Python 3.13 Alpine, ~110MB, non-root user)
docker build -t random-number-server:latest .

# Alternatively, use Docker Compose to build
docker-compose build

Run and manage with Docker Compose

# Production run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

Run the MCP server locally with UV (stdio method)

uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/random-number-server run src/random_server.py

Configure Claude Desktop for MCP access (example)

{
  "mcpServers": {
    "weather": {
      "command": "/Users/Nobel.Khandaker/.pyenv/shims/uv",
      "args": [
        "--directory",
        "/Users/Nobel.Khandaker/sources/random-number-server",
        "run",
        "src/random_server.py"
      ]
    }
  }
}

Notes on environment and tools

No extra environment variables are required by default for the weather server. If you later introduce environment-based configuration (for example, API keys for weather data sources), document them in your client’s startup configuration and include them in the environment descriptor of your MCP server instance.

Examples and troubleshooting

If you encounter issues starting the server, verify the working directory path is correct, ensure Python dependencies are installed, and confirm the UV runtime is accessible in your shell. For unit tests, run through the project’s test suite with the provided commands to confirm core modules and weather-based seeding logic are functioning as expected.