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

Related MCP server: replicant-mcp

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.

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.