Skip to main content
Glama

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

Related MCP server: mcp-creator

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.

Available Tools

2 tools
nox_list_sessionsA

List all available nox sessions.

Use this tool to discover which nox sessions are available in the current project before running them. Returns structured session data including session names, Python versions, and descriptions.

Returns: A list of session objects, each containing session metadata like 'session' (name), 'python' (version), and 'description'.

Example response: [{"session": "tests", "python": "3.11", "description": "Run tests"}]

Inputs: timeout. Returns: result

nox_run_sessionA

Run nox sessions.

Use this tool to execute one or more nox sessions in the current project. You can filter sessions by name, tags, or keywords. Use nox_list_sessions first to discover available sessions.

Args: sessions: List of session names to run (e.g., ["tests", "lint"]). Session names must contain only alphanumeric characters, hyphens, or underscores. tags: List of tags to filter sessions (e.g., ["ci", "quick"]). Only sessions matching these tags will run. keywords: A keyword expression to filter sessions (e.g., "test and not slow"). Uses Python expression syntax for matching session names. python: Python version to run sessions with (e.g., "3.11", "3.12"). Overrides the session's default Python version. timeout: Maximum seconds to wait for nox to complete. Defaults to 300.

Returns: A dictionary with 'exit_code' (0 = success), 'stdout', and 'stderr' from the nox command execution.

Example: Run tests with Python 3.11: nox_run_session(sessions=["tests"], python="3.11")

Inputs: sessions, tags, keywords, python, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one lists available sessions, the other runs them. There is no overlap or ambiguity.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun pattern with 'nox_' prefix (nox_list_sessions, nox_run_session), making them predictable and easy to understand.

    Tool Count4/5

    With only 2 tools, the server is minimal but appropriately scoped for listing and running nox sessions. It covers the essential interactions without unnecessary complexity.

    Completeness5/5

    The tool set is complete for its intended purpose: discovering available sessions and executing them. There are no missing operations since sessions are defined externally in noxfiles.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A tool that enables AI assistants to conversationally scaffold, build, and publish Python MCP servers to PyPI. It automates the entire development lifecycle, including package naming, tool scaffolding, GitHub repository setup, and package publishing.
      10
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI agents to list and run tasks defined in Taskfile.yml, useful for automated development workflows.
      2
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that bridges AI assistants to real terminal sessions, enabling creation, management, and interaction with persistent PTY processes for running commands, monitoring output, and debugging.
      1
      MIT