nox-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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
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-mcpOr with uv:
uv pip install nox-mcpQuick 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 descriptionnox_run_session
Run one or more nox sessions.
Parameter | Type | Description |
| list[str] | Session names to run (e.g., |
| list[str] | Filter sessions by tags |
| str | Keyword expression (e.g., |
| str | Python version override (e.g., |
| int | Max seconds to wait (default: 300) |
Example Workflow
Ask your AI assistant: "What nox sessions are available?"
The assistant calls
nox_list_sessionsand shows you the optionsAsk: "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 checkLicense
MIT License — see LICENSE for details.
Available Tools
2 toolsnox_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
Scored across 2 tools
The two tools have clearly distinct purposes: one lists available sessions, the other runs them. There is no overlap or ambiguity.
Both tools follow a consistent verb_noun pattern with 'nox_' prefix (nox_list_sessions, nox_run_session), making them predictable and easy to understand.
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.
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
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Official Duck Framework MCP server for AI-assisted development and project scaffolding.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that supercharges AI assistants with powerful tools for software development, enabling research, planning, code generation, and project scaffolding through natural language interaction.1142 npm102MIT
- AlicenseAqualityBmaintenanceA 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.10MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables AI agents to list and run tasks defined in Taskfile.yml, useful for automated development workflows.24MIT
- AlicenseNot gradedqualityDmaintenanceAn 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.1MIT