feat: logging control through MCP_REDIS_LOG_LEVEL env var

Author: vchomakov

README.md

@@ -37,6 +37,7 @@ The Redis MCP Server is a **natural language interface** designed for agentic ap
   - [Redis ACL](#redis-acl)
   - [Configuration via command line arguments](#configuration-via-command-line-arguments)
   - [Configuration via Environment Variables](#configuration-via-environment-variables)
+  - [Logging](#logging)
 - [Integrations](#integrations)
   - [OpenAI Agents SDK](#openai-agents-sdk)
   - [Augment](#augment)
@@ -78,7 +79,7 @@ Additional tools.
 
 ## Installation
 
-The Redis MCP Server is available as a PyPI package and as direct installation from the GitHub repository. 
+The Redis MCP Server is available as a PyPI package and as direct installation from the GitHub repository.
 
 ### From PyPI (recommended)
 Configuring the latest Redis MCP Server version from PyPI, as an example, can be done importing the following JSON configuration in the desired framework or tool.
@@ -125,7 +126,7 @@ However, starting the MCP Server is most useful when delegate to the framework o
 
 You can configure the desired Redis MCP Server version with `uvx`, which allows you to run it directly from GitHub (from a branch, or use a tagged release).
 
-> It is recommended to use a tagged release, the `main` branch is under active development and may contain breaking changes. 
+> It is recommended to use a tagged release, the `main` branch is under active development and may contain breaking changes.
 
 As an example, you can execute the following command to run the `0.2.0` release:
 
@@ -140,7 +141,7 @@ Additional examples are provided below.
 # Run with Redis URI
 uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --url redis://localhost:6379/0
 
-# Run with Redis URI and SSL 
+# Run with Redis URI and SSL
 uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --url "rediss://<USERNAME>:<PASSWORD>@<HOST>:<PORT>?ssl_cert_reqs=required&ssl_ca_certs=<PATH_TO_CERT>"
 
 # Run with individual parameters
@@ -318,7 +319,7 @@ If desired, you can use environment variables. Defaults are provided for all var
 
 There are several ways to set environment variables:
 
-1. **Using a `.env` File**:  
+1. **Using a `.env` File**:
 Place a `.env` file in your project directory with key-value pairs for each environment variable. Tools like `python-dotenv`, `pipenv`, and `uv` can automatically load these variables when running your application. This is a convenient and secure way to manage configuration, as it keeps sensitive data out of your shell history and version control (if `.env` is in `.gitignore`).
 For example, create a `.env` file with the following content from the `.env.example` file provided in the repository:
 
@@ -330,7 +331,7 @@ Then edit the `.env` file to set your Redis configuration:
 
 OR,
 
-2. **Setting Variables in the Shell**:  
+2. **Setting Variables in the Shell**:
 You can export environment variables directly in your shell before running your application. For example:
 
 ```sh
@@ -342,6 +343,46 @@ export REDIS_PORT=6379
 This method is useful for temporary overrides or quick testing.
 
 
+### Logging
+
+The server uses Python's standard logging and is configured at startup. By default it logs at WARNING and above. You can change verbosity with the `MCP_REDIS_LOG_LEVEL` environment variable.
+
+- Accepted values (case-insensitive): `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`, `NOTSET`
+- Aliases supported: `WARN` → `WARNING`, `FATAL` → `CRITICAL`
+- Numeric values are also accepted, including signed (e.g., `"10"`, `"+20"`)
+- Default when unset or unrecognized: `WARNING`
+
+Handler behavior
+- If the host (e.g., `uv`, VS Code, pytest) already installed console handlers, the server will NOT add its own; it only lowers overly-restrictive handler thresholds so your chosen level is not filtered out. It will never raise a handler's threshold.
+- If no handlers are present, the server adds a single stderr StreamHandler with a simple format.
+
+Examples
+```bash
+# See normal lifecycle messages
+MCP_REDIS_LOG_LEVEL=INFO uv run src/main.py
+
+# Very verbose for debugging
+MCP_REDIS_LOG_LEVEL=DEBUG uvx --from redis-mcp-server@latest redis-mcp-server --url redis://localhost:6379/0
+```
+
+In MCP client configs that support env, add it alongside your Redis settings. For example:
+```json
+{
+  "mcpServers": {
+    "redis": {
+      "command": "uvx",
+      "args": ["--from", "redis-mcp-server@latest", "redis-mcp-server", "--url", "redis://localhost:6379/0"],
+      "env": {
+        "REDIS_HOST": "localhost",
+        "REDIS_PORT": "6379",
+        "MCP_REDIS_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
+
+
 ## Integrations
 
 Integrating this MCP Server to development frameworks like OpenAI Agents SDK, or with tools like Claude Desktop, VS Code, or Augment is described in the following sections.
@@ -439,7 +480,7 @@ You can start the GitHub desired version of the Redis MCP server using `uvx` by
     "servers": {
         "Redis MCP Server": {
         "type": "stdio",
-        "command": "uvx", 
+        "command": "uvx",
         "args": [
             "--from", "redis-mcp-server@latest",
             "redis-mcp-server",

src/common/connection.py

@@ -1,4 +1,4 @@
-import sys
+import logging
 from typing import Optional, Type, Union
 
 import redis
@@ -8,6 +8,8 @@
 from src.common.config import REDIS_CFG
 from src.version import __version__
 
+_logger = logging.getLogger(__name__)
+
 
 class RedisConnectionManager:
     _instance: Optional[Redis] = None
@@ -57,25 +59,25 @@ def get_connection(cls, decode_responses=True) -> Redis:
                 cls._instance = redis_class(**connection_params)
 
             except redis.exceptions.ConnectionError:
-                print("Failed to connect to Redis server", file=sys.stderr)
+                _logger.error("Failed to connect to Redis server")
                 raise
             except redis.exceptions.AuthenticationError:
-                print("Authentication failed", file=sys.stderr)
+                _logger.error("Authentication failed")
                 raise
             except redis.exceptions.TimeoutError:
-                print("Connection timed out", file=sys.stderr)
+                _logger.error("Connection timed out")
                 raise
             except redis.exceptions.ResponseError as e:
-                print(f"Response error: {e}", file=sys.stderr)
+                _logger.error("Response error: %s", e)
                 raise
             except redis.exceptions.RedisError as e:
-                print(f"Redis error: {e}", file=sys.stderr)
+                _logger.error("Redis error: %s", e)
                 raise
             except redis.exceptions.ClusterError as e:
-                print(f"Redis Cluster error: {e}", file=sys.stderr)
+                _logger.error("Redis Cluster error: %s", e)
                 raise
             except Exception as e:
-                print(f"Unexpected error: {e}", file=sys.stderr)
+                _logger.error("Unexpected error: %s", e)
                 raise
 
         return cls._instance

src/common/logging_utils.py

@@ -0,0 +1,62 @@
+import logging
+import os
+import sys
+
+
+def resolve_log_level() -> int:
+    """Resolve desired log level from MCP_REDIS_LOG_LEVEL.
+
+    Accepts numeric strings or standard level names (DEBUG, INFO, WARNING,
+    ERROR, CRITICAL, NOTSET) including aliases WARN and FATAL. Defaults to WARNING.
+    """
+    name = os.getenv("MCP_REDIS_LOG_LEVEL")
+    if name:
+        s = name.strip()
+        try:
+            return int(s)
+        except ValueError:
+            pass
+        level = getattr(logging, s.upper(), None)
+        if isinstance(level, int):
+            return level
+    return logging.WARNING
+
+
+def configure_logging() -> int:
+    """Configure logging based on environment.
+
+    - Default level WARNING
+    - MCP_REDIS_LOG_LEVEL to override
+
+    Returns the resolved log level. Idempotent.
+    """
+
+    level = resolve_log_level()
+    root = logging.getLogger()
+
+    # Always set the root logger level
+    root.setLevel(level)
+
+    # Only lower overly-restrictive handler thresholds to avoid host filtering.
+    # - Leave NOTSET (0) alone so it defers to logger/root levels
+    # - Do not raise handler thresholds (respect host-configured verbosity)
+    for h in root.handlers:
+        try:
+            cur = getattr(h, "level", None)
+            if isinstance(cur, int) and cur != logging.NOTSET and cur > level:
+                h.setLevel(level)
+        except Exception:
+            pass
+
+    # Only add our own stderr handler if there are NO handlers at all.
+    # Many hosts (pytest, uv, VS Code) install a console handler already.
+    if not root.handlers:
+        sh = logging.StreamHandler(sys.stderr)
+        sh.setLevel(level)
+        sh.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+        root.addHandler(sh)
+
+    # Route warnings.warn(...) through logging
+    logging.captureWarnings(True)
+
+    return level

src/main.py

@@ -1,14 +1,19 @@
 import sys
+import logging
 
 import click
 
 from src.common.config import parse_redis_uri, set_redis_config_from_cli
 from src.common.server import mcp
+from src.common.logging_utils import configure_logging
 
 
 class RedisMCPServer:
     def __init__(self):
-        print("Starting the Redis MCP Server", file=sys.stderr)
+        # Configure logging on server initialization (idempotent)
+        configure_logging()
+        self._logger = logging.getLogger(__name__)
+        self._logger.info("Starting the Redis MCP Server")
 
     def run(self):
         mcp.run()

tests/test_integration.py

@@ -240,9 +240,9 @@ def test_server_lists_tools(self, server_process):
             "get",
         ]
         for tool in tool_names:
-            assert tool in expected_tools, (
-                f"Expected tool '{tool}' not found in {tool_names}"
-            )
+            assert (
+                tool in expected_tools
+            ), f"Expected tool '{tool}' not found in {tool_names}"
 
     def test_server_tool_count_and_names(self, server_process):
         """Test that the server registers the correct number of tools with expected names."""
@@ -269,9 +269,9 @@ def test_server_tool_count_and_names(self, server_process):
 
         # Expected tool count (based on @mcp.tool() decorators in codebase)
         expected_tool_count = 44
-        assert len(tools) == expected_tool_count, (
-            f"Expected {expected_tool_count} tools, but got {len(tools)}"
-        )
+        assert (
+            len(tools) == expected_tool_count
+        ), f"Expected {expected_tool_count} tools, but got {len(tools)}"
 
         # Expected tool names (alphabetically sorted for easier verification)
         expected_tools = [
@@ -360,9 +360,9 @@ def test_server_tool_count_and_names(self, server_process):
 
         for category, category_tools in tool_categories.items():
             for tool in category_tools:
-                assert tool in tool_names, (
-                    f"Tool '{tool}' from category '{category}' not found in registered tools"
-                )
+                assert (
+                    tool in tool_names
+                ), f"Tool '{tool}' from category '{category}' not found in registered tools"
 
     def _initialize_server(self, server_process):
         """Helper to initialize the MCP server."""