Skip to main content
Glama
rvforest

nox-mcp

by rvforest
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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"}]

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It indicates a read-only operation ('List') and describes the return format with an example, which is sufficient for a listing tool. No destructive behavior is suggested.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, well-structured with separate sections for purpose, usage hint, return type, and example. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema is fully described via the example, and the single parameter is optional with a default. However, the lack of explanation for the 'timeout' parameter leaves a minor gap in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter 'timeout' with a default of 30, but the description does not mention this parameter at all. Since schema coverage is 0%, the description should explain it; its absence is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('all available nox sessions'), clearly stating the tool's purpose. It also contrasts with the sibling tool 'nox_run_session' by implying this is for discovery before running.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this tool to discover which nox sessions are available in the current project before running them,' providing clear context and implied timing. However, it does not explicitly state when not to use it or mention alternatives beyond the sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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")

ParametersJSON Schema
NameRequiredDescriptionDefault
sessionsNo
tagsNo
keywordsNo
pythonNo
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes basic behavior (running nox sessions) and return values, but lacks details on destructive actions, auth needs, or error conditions beyond exit codes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured with intro, args, returns, and example. Front-loaded purpose, every sentence adds value. No redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers usage, parameters, return values, and example. Output schema exists. Minor gaps: doesn't specify error handling for invalid sessions or timeouts, but adequate for a command-executing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but description provides thorough parameter documentation: constraints on sessions (alphanumeric, hyphens, underscores), tags (list), keywords (expression), python version, timeout default. Adds significant meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Run' and resource 'nox sessions', specifying execution of one or more sessions. It distinguishes from sibling tool nox_list_sessions by advising to list sessions first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises to use nox_list_sessions first to discover sessions, providing clear context. It mentions filtering options but does not explicitly state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observednox_list_sessions
    • First observednox_run_session
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
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.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • mcp-creator

    gmoneyn
    A
    license
    A
    quality
    C
    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

  • gotask-mcp

    PaddyAlton
    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

  • terminal-bridge-mcp

    dividduang
    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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rvforest/nox-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server