How do I use nox-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@nox-mcp Run the tests using Python 3.12" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

nox-mcp

License: MIT

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

Ask your AI assistant: "What nox sessions are available?"
The assistant calls nox_list_sessions and shows you the options
Ask: "Run the tests with Python 3.12"
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