nox-mcp

<!--

-->

A Model Context Protocol (MCP) server that enables AI assistants to run nox sessions. This allows LLMs to discover and execute your project's test, lint, build, and other automation tasks.

Features

• Discover sessions — List all available nox sessions with descriptions and Python versions
• Run sessions — Execute sessions by name, tags, or keyword expressions
• Filter by Python version — Override the default Python version for any session
• Structured output — Returns JSON responses for easy parsing by AI tools

Installation

Requires Python 3.10+ and nox installed in your PATH.

pip install nox-mcp

Or with uv:

uv pip install nox-mcp

Quick Start

Configure your MCP client

Add nox-mcp to your MCP client configuration. For example, in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "nox": {
      "command": "nox-mcp"
    }
  }
}

Or if using uvx:

{
  "mcpServers": {
    "nox": {
      "command": "uvx",
      "args": ["nox-mcp"]
    }
  }
}

Available Tools

Once configured, your AI assistant can use these tools:

nox_list_sessions

List all available nox sessions in the current project.

Returns: List of session objects with name, python version, and description

nox_run_session

Run one or more nox sessions.

Parameter	Type	Description
sessions	list[str]	Session names to run (e.g., ["tests", "lint"])
tags	list[str]	Filter sessions by tags
keywords	str	Keyword expression (e.g., "test and not slow")
python	str	Python version override (e.g., "3.12")
timeout	int	Max seconds to wait (default: 300)

Example Workflow

1. Ask your AI assistant: "What nox sessions are available?"
2. The assistant calls nox_list_sessions and shows you the options
3. Ask: "Run the tests with Python 3.12"
4. The assistant calls nox_run_session(sessions=["tests"], python="3.12")

Requirements

• Python 3.10+
• nox installed and available in PATH
• An MCP-compatible client (Claude Desktop, etc.)

Development

# Clone the repository
git clone https://github.com/rvforest/nox-mcp.git
cd nox-mcp

# Install dependencies
uv sync

# Run tests
uv run nox -s test

# Run all checks
uv run nox -s check

License

MIT License — see LICENSE for details.