# nox-mcp
<!--
[](https://pypi.org/project/nox-mcp/)
[](https://pypi.org/project/nox-mcp/)
[](https://github.com/rvforest/nox-mcp)
[](https://nox-mcp.readthedocs.io)
[](https://github.com/rvforest/nox-mcp/actions/workflows/run-checks.yaml?query=branch%3Amain)
[](https://codecov.io/gh/rvforest/nox-mcp)
[](https://pypi.org/project/nox-mcp/)
[](https://pypi.org/project/nox-mcp/)
-->
[](https://opensource.org/licenses/MIT)
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants to run [nox](https://nox.thea.codes/) 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](https://nox.thea.codes/) installed in your PATH.
```bash
pip install nox-mcp
```
Or with [uv](https://docs.astral.sh/uv/):
```bash
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`:
```json
{
"mcpServers": {
"nox": {
"command": "nox-mcp"
}
}
}
```
Or if using uvx:
```json
{
"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](https://nox.thea.codes/) installed and available in PATH
- An MCP-compatible client (Claude Desktop, etc.)
## Development
```bash
# 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](LICENSE) for details.
