udondan/switch-parental-controls repository overview

⁠switch-parental-controls

Monitor and manage Nintendo Switch Parental Controls from the terminal and from AI assistants: devices, daily summaries, monthly playtime, playtime limits, bedtime, restrictions, players and the app allow-list.

The image contains the switch-parental-controls command line interface and an MCP⁠ server for AI assistants such as Claude. Most commands only read data. The set-* commands and add-extra-time change the settings on your Switch. It uses the unofficial Nintendo Parental Controls API through pynintendoparental⁠.

Source code, full documentation and the PyPI package: github.com/udondan/switch-parental-controls⁠

⁠Tags

• latest: newest release
• X.Y.Z: exactly this version
• X.Y, X: newest release of this minor or major version

Platforms: linux/amd64 and linux/arm64.

⁠Credentials

The image stores the session token and the caches in /data. Mount a volume there so they survive between runs. Log in once (-it for the interactive prompt):

docker run --rm -it -v switch-parental-controls:/data udondan/switch-parental-controls login

1. Open the printed Nintendo login URL in your browser
2. Log in with your Nintendo Account
3. Right-click the "Select this person" button and copy the link
4. Paste the copied link at the prompt

Instead of the volume, the token can come from an environment variable:

login also prints the token, so you can copy it into the variable. Session tokens can expire. If you get authentication errors, log in again.

⁠Command line

With an alias, the image behaves like an installed switch-parental-controls. -e NAME without a value takes the variable from your shell, if set:

alias switch-parental-controls='docker run --rm -i -e SWITCH_PARENTAL_CONTROLS_TIMEZONE -e SWITCH_PARENTAL_CONTROLS_LANG -v switch-parental-controls:/data udondan/switch-parental-controls'

switch-parental-controls list-devices
switch-parental-controls today-summary
switch-parental-controls set-playtime-limit --minutes 120
switch-parental-controls add-extra-time 30

Device commands take an optional device name or ID. With only one Switch on the account, it is selected automatically. Output is Markdown, or JSON with --format json. switch-parental-controls --help lists all commands: list-devices, today-summary, monthly-summary, playtime, set-playtime-limit, add-extra-time, set-day-restrictions, set-bedtime-alarm, set-restriction-mode, set-content-restriction, list-players, list-applications, set-app-allow-list and more.

⁠MCP server

Without arguments, the image starts the MCP server (stdio). Entry for Claude Desktop:

{
  "mcpServers": {
    "nintendo": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "SWITCH_PARENTAL_CONTROLS_SESSION_TOKEN", "-e", "SWITCH_PARENTAL_CONTROLS_TIMEZONE", "-e", "SWITCH_PARENTAL_CONTROLS_LANG", "udondan/switch-parental-controls"],
      "env": {
        "SWITCH_PARENTAL_CONTROLS_SESSION_TOKEN": "your-token-here",
        "SWITCH_PARENTAL_CONTROLS_TIMEZONE": "America/New_York",
        "SWITCH_PARENTAL_CONTROLS_LANG": "en-US"
      }
    }
  }
}

⁠Docker MCP Toolkit

With the Docker MCP Toolkit, the token is stored as a secret in Docker Desktop instead of in plain text in the client configuration:

mkdir -p ~/.docker/mcp/catalogs
curl -fsSL https://raw.githubusercontent.com/udondan/switch-parental-controls/main/docker-mcp.yml -o ~/.docker/mcp/catalogs/switch-parental-controls.yml
docker mcp profile create --name switch-parental-controls --id switch-parental-controls --server "file://$HOME/.docker/mcp/catalogs/switch-parental-controls.yml"

docker mcp secret set switch-parental-controls.session_token=your-token-here

docker mcp client connect claude-desktop --profile switch-parental-controls

Timezone and language are optional profile settings. Details in the README⁠.

⁠Signature

The images are signed with cosign⁠ by the release workflow on GitHub:

cosign verify udondan/switch-parental-controls:latest \
  --certificate-identity-regexp '^https://github\.com/udondan/switch-parental-controls/\.github/workflows/publish\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Each image also carries SBOM and provenance attestations.

⁠Security

The container runs as the unprivileged user switch (UID 10001). The image is based on the official Python Alpine image, without pip.

⁠Legal

Nintendo and Nintendo Switch are trademarks or registered trademarks of Nintendo in the U.S. and/or other countries. This project is not affiliated, funded, or in any way associated with Nintendo.

⁠License

MIT⁠