nws-mcp

An unofficial Model Context Protocol (MCP) server for New World Scheduler (NWS). It lets Claude and other MCP clients read and manage a congregation's NWS data headlessly: people, schedules, assignments, territories, public witnessing, public-speaker sharing, NWP app publishing, backups and more, without automating the Windows UI.

Disclaimer. Unofficial. Not affiliated with or endorsed by the developers of New World Scheduler. Uses your own NWS credentials; you are responsible for complying with NWS terms.

It works on the congregation's live shared data. Every write goes through a preview and an explicit confirmation step, and nothing is published to the NWP app or announced by push notification unless you ask for it.

Contents

• Features

• Safety model

• Requirements

• Install

• Configuration

• MCP client setup

• First steps

• Development

• Documentation

• License

Related MCP server: srgplus-mcp

Features

62 tools across these areas (full list with parameters in docs/tools.md):

Safety model

Summary (details in docs/safety.md):

• Preview, confirmation ID, commit. Every write is a preview that returns a ten-minute, single-use confirmation ID. The commit re-checks that nothing changed since the preview and refuses stale data. A cancel tool discards the preview.

• No implicit publish or notify. Committing a change never publishes to the NWP app and never sends notifications. Publishing is its own preview/commit step, and send_notifications must be passed explicitly as true or false.

• Permissions enforced. The authenticated person's NWS access rights are applied as in NWS Desktop; edit, restore, publish and report-view rights are checked before writing or returning data.

• Destructive restores additionally require overwrite_existing_data=true on both preview and commit.

• Secrets stay local. Credentials come only from your environment; tool output never contains passwords, PINs or tokens; local files are owner-only.

Requirements

• Python 3.11 or newer.

• An NWS congregation-sharing account (congregation ID, congregation password, and the email address of your NWS user). Write operations only work as far as your NWS access rights allow.

• A vendor configuration file for NWS (see Configuration).

Install

python -m venv .venv
. .venv/bin/activate
python -m pip install .

This installs the nws-mcp command, a stdio MCP server.

Configuration

The server is configured only through environment variables, normally set in your MCP client's server entry.

Vendor configuration file. The server needs a vendor configuration file for the NWS backend, given by NWS_VENDOR_CONFIG_PATH. That file is not distributed with this project and this project does not explain how to obtain it. Without it, the server cannot connect.

Keep all of these values, the vendor configuration file and the state directory out of version control. The state directory holds decrypted congregation data with owner-only permissions.

The server currently targets one NWS sharing region and one NWP app server (region ID 15, app server ID 5). Other regions are not configurable yet.

MCP client setup

Claude Code

claude mcp add nws \
  -e NWS_CONGREGATION_ID=123-456-789 \
  -e NWS_CONGREGATION_PASSWORD='your-password' \
  -e NWS_EMAIL=you@example.org \
  -e NWS_CONGREGATION_PIN='your-app-pin' \
  -e NWS_VENDOR_CONFIG_PATH=/path/to/vendor-config.json \
  -- /path/to/.venv/bin/nws-mcp

Or in a project .mcp.json (do not commit real credentials):

{
  "mcpServers": {
    "nws": {
      "command": "/path/to/.venv/bin/nws-mcp",
      "env": {
        "NWS_CONGREGATION_ID": "123-456-789",
        "NWS_CONGREGATION_PASSWORD": "your-password",
        "NWS_EMAIL": "you@example.org",
        "NWS_CONGREGATION_PIN": "your-app-pin",
        "NWS_VENDOR_CONFIG_PATH": "/path/to/vendor-config.json"
      }
    }
  }
}

Claude Desktop

Add the same entry to claude_desktop_config.json (Settings, Developer, Edit Config):

{
  "mcpServers": {
    "nws": {
      "command": "/path/to/.venv/bin/nws-mcp",
      "env": {
        "NWS_CONGREGATION_ID": "123-456-789",
        "NWS_CONGREGATION_PASSWORD": "your-password",
        "NWS_EMAIL": "you@example.org",
        "NWS_CONGREGATION_PIN": "your-app-pin",
        "NWS_VENDOR_CONFIG_PATH": "/path/to/vendor-config.json",
        "NWS_STATE_DIR": "/path/to/private/nws-state"
      }
    }
  }
}

On Windows use paths such as C:\\Users\\you\\nws\\.venv\\Scripts\\nws-mcp.exe.

First steps

1. nws_status to check that the configuration loads.

2. nws_authenticate. On a new device NWS emails a verification code; pass it to nws_verify.

3. nws_sync to fill the local mirror, then nws_entity_types, nws_list and nws_get to read.

4. To change something: nws_preview_change, review, then nws_commit_change with the confirmation ID.

5. To release changes to the NWP app: nws_app_authenticate, nws_app_preview_publish, review, then nws_app_commit_publish with send_notifications set to true or false.

Development

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[test]'
python -m pytest

The test suite runs fully offline: protocol tests use in-memory HTTP transports and never contact NWS.

Layout:

• src/nws_mcp/server.py: MCP tool definitions.

• src/nws_mcp/protocol.py: authentication, Firestore and cloud-function client.

• src/nws_mcp/schema.py and src/nws_mcp/data/schema.json: wire-name to friendly-name mappings and NWP field allow-lists.

• other modules: one per subsystem (publish, import, backup, attachments, print layouts, public witnessing, public-speaker sharing, auto-assignment).

Documentation

• docs/tools.md: every tool, its parameters and behaviour.

• docs/safety.md: the safety model.

• docs/capabilities.md: the capability matrix, including unsupported and UI-only items.

• docs/design/: design notes.

License

MIT. Copyright 2026 DezinerDudes.

"New World Scheduler", "NWS" and "NW Publisher" are names of their respective owners and are used here only to describe compatibility.