switch-parental-controls 0.3.0

Nintendo Switch Parental Controls

Nintendo Switch Parental Controls

A CLI and MCP (Model Context Protocol) server that expose Nintendo Switch Parental Controls as commands and AI-accessible tools. It wraps the pynintendoparental library and allows humans and AI assistants to monitor and manage parental control settings on Nintendo Switch devices.

Features

• Authentication: Interactive Nintendo OAuth login flow, or pre-configured session token
• Device monitoring: List devices, view playtime, remaining time, sync status
• Playtime controls: Set daily limits, add extra time, configure per-day-of-week schedules
• Bedtime controls: Set bedtime alarms and end times
• Restriction controls: Set restriction mode (forced termination vs. alarm), content restriction levels
• Player tracking: View player profiles and today's app usage
• Application management: List apps, manage the allow-list (bypass content restrictions)

Prerequisites

• uv — install once, no Python or clone needed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Authentication: Getting Your Nintendo Session Token

The server requires a Nintendo session token to access the Parental Controls API. You can obtain one in two ways:

Method 1: Interactive MCP Tool (Recommended for first-time setup)

1. Start the MCP server (see below)
2. Ask your AI assistant to call nintendo_get_login_url
3. Open the returned URL in your browser
4. Log in with your Nintendo Account
5. On the "Select this person" page, right-click the "Select this person" button and copy the link
6. Ask your AI assistant to call nintendo_complete_login with the copied URL
7. The tool will return your session token — save it!

Method 2: Manual (if you already have a token)

If you already have a session token, set it as an environment variable:

export NINTENDO_SESSION_TOKEN="your-token-here"

Saving Your Token

Once you have a session token, add it to your environment so you don't need to log in again:

# Add to your shell profile (~/.zshrc, ~/.bashrc, etc.)
export NINTENDO_SESSION_TOKEN="your-token-here"

# Or create a .env file (never commit this!)
echo 'NINTENDO_SESSION_TOKEN=your-token-here' >> .env

Note: Session tokens can expire. If you get authentication errors, repeat the login flow.

CLI Usage

The switch-parental-controls CLI gives you direct terminal access to all parental control features.

Installation

No clone required — run directly with uvx:

uvx switch-parental-controls --help

Or install globally:

pip install switch-parental-controls
switch-parental-controls --help

Login

switch-parental-controls login

This starts an interactive flow:

1. A Nintendo login URL is printed — open it 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 URL at the prompt

On success, the token is saved to ~/.config/switch-parental-controls/credentials — all other commands will use it automatically. No further setup needed.

For CI pipelines or other tools that need the token directly, the export snippet is also printed during login.

Global Options

switch-parental-controls [OPTIONS] COMMAND [ARGS]...

Options:
  -t, --timezone TEXT   IANA timezone  [env: NINTENDO_TIMEZONE; default: Europe/London]
  -l, --lang TEXT       Language code  [env: NINTENDO_LANG; default: en-GB]

Commands

All device commands accept an optional [DEVICE] argument — a device name or ID. If omitted and the account has exactly one Switch, it is auto-selected. Run list-devices once to populate the local cache.

Device info:

switch-parental-controls list-devices [--format markdown|json]
switch-parental-controls get-device [DEVICE] [--format markdown|json]
switch-parental-controls today-summary [DEVICE] [--format markdown|json]
switch-parental-controls monthly-summary [DEVICE] [--year YEAR --month MONTH] [--format markdown|json]

# DEVICE may be a name or an ID
switch-parental-controls today-summary "Switch #1"
switch-parental-controls today-summary abc123def456

Playtime limits:

switch-parental-controls set-playtime-limit [DEVICE] --minutes 120   # set 2-hour limit
switch-parental-controls set-playtime-limit [DEVICE] --no-limit       # remove limit
switch-parental-controls add-extra-time [DEVICE] 30                   # add 30 extra minutes today
switch-parental-controls set-timer-mode [DEVICE] DAILY
switch-parental-controls set-timer-mode [DEVICE] EACH_DAY_OF_THE_WEEK

Per-day restrictions:

# Enable playtime + bedtime on Monday
switch-parental-controls set-day-restrictions [DEVICE] MONDAY \
  --playtime-enabled --max-playtime-minutes 90 \
  --bedtime-enabled \
  --bedtime-alarm-hour 21 --bedtime-alarm-minute 0 \
  --bedtime-end-hour 7 --bedtime-end-minute 0

# Disable all restrictions on Saturday
switch-parental-controls set-day-restrictions [DEVICE] SATURDAY \
  --playtime-disabled --bedtime-disabled

Restriction and content controls:

switch-parental-controls set-restriction-mode [DEVICE] FORCED_TERMINATION
switch-parental-controls set-restriction-mode [DEVICE] ALARM
switch-parental-controls set-content-restriction [DEVICE] CHILDREN
switch-parental-controls set-bedtime-alarm [DEVICE] 21 0    # 21:00
switch-parental-controls set-bedtime-alarm [DEVICE] 0 0     # disable
switch-parental-controls set-bedtime-end [DEVICE] 7 0       # 07:00

Players and applications:

switch-parental-controls list-players [DEVICE] [--format json]
switch-parental-controls get-player [DEVICE] <player-id>
switch-parental-controls list-applications [DEVICE]
switch-parental-controls set-app-allow-list [DEVICE] <app-id> --allow
switch-parental-controls set-app-allow-list [DEVICE] <app-id> --no-allow

Start the MCP server:

switch-parental-controls mcp

Running the Server

uvx switch-parental-controls mcp

No clone or install required — uvx fetches the package from PyPI and runs it in an isolated environment.

Environment Variables

Variable	Required	Default	Description
NINTENDO_SESSION_TOKEN	No*	—	Nintendo session token
NINTENDO_TIMEZONE	No	Europe/London	IANA timezone (e.g. America/New_York)
NINTENDO_LANG	No	en-GB	Language code (e.g. en-US)

*Required for any tool that accesses Nintendo data, unless you use the interactive login tools.

MCP Client Configuration

Add to your MCP client configuration (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "nintendo": {
      "command": "uvx",
      "args": ["switch-parental-controls", "mcp"],
      "env": {
        "NINTENDO_SESSION_TOKEN": "your-token-here",
        "NINTENDO_TIMEZONE": "America/New_York",
        "NINTENDO_LANG": "en-US"
      }
    }
  }
}

Available Tools

Authentication

Tool	Description
nintendo_get_login_url	Generate the Nintendo login URL and step-by-step instructions
nintendo_complete_login	Complete login with the redirect URL from the browser

Devices

Tool	Description
nintendo_list_devices	List all Nintendo Switch devices on the account
nintendo_get_device	Get detailed status for a specific device
nintendo_get_today_summary	Get today's usage summary for a device
nintendo_get_monthly_summary	Get monthly usage summary (optionally for a specific month)

Playtime Controls

Tool	Description
nintendo_set_daily_playtime_limit	Set the daily playtime limit (0-360 min, or -1 to remove)
nintendo_add_extra_time	Add extra playtime for today
nintendo_set_timer_mode	Switch between DAILY and EACH_DAY_OF_THE_WEEK modes
nintendo_set_day_restrictions	Set per-day playtime and bedtime restrictions

Restriction Controls

Tool	Description
nintendo_set_restriction_mode	Set FORCED_TERMINATION or ALARM mode
nintendo_set_content_restriction_level	Set age-based content restrictions
nintendo_set_bedtime_alarm	Set the bedtime alarm time (16:00-23:00)
nintendo_set_bedtime_end_time	Set when bedtime ends (05:00-09:00)

Players

Tool	Description
nintendo_list_players	List all players on a device
nintendo_get_player	Get player details including apps played today

Applications

Tool	Description
nintendo_list_applications	List all tracked applications on a device
nintendo_set_app_allow_list	Add/remove an app from the content restriction allow-list

Development

Requires mise:

# Install dependencies
mise run install

# Run tests
mise run test

# Run linter
mise run lint

# Fix lint issues
mise run lint-fix

# Open MCP Inspector (browser UI to test tools interactively)
mise run inspect

MCP Inspector

The inspect task launches the MCP Inspector — a browser-based UI for testing MCP tools interactively without needing a full AI client.

mise run inspect

This opens the inspector connected to the switch_parental_controls server. You can call any tool directly from the UI, which is useful for testing the authentication flow and verifying tool responses.

Testing with opencode locally

An example opencode config is provided at opencode.jsonc.example. To use it:

# 1. Copy the example config
cp opencode.jsonc.example opencode.jsonc

# 2. Optionally set NINTENDO_SESSION_TOKEN in opencode.jsonc

# 3. Open opencode in this project directory — it will pick up the local config
opencode

The local opencode.jsonc is gitignored so your session token stays private.

CI

Tests run automatically on pull requests via GitHub Actions. See .github/workflows/test.yml.

License

MIT