nws-mcp

Open source · MIT

NWS MCP

An unofficial MCP server for New World Scheduler.

Let Claude and other MCP clients read and safely manage your congregation’s NWS data, without automating the Windows UI. Every change is previewed and confirmed first.

View on GitHub Read the docs

Unofficial project

This project is not affiliated with or endorsed by the developers of New World Scheduler. It uses your own NWS credentials, and you are responsible for complying with NWS terms. “New World Scheduler”, “NWS” and “NW Publisher” are names of their respective owners, used here only to describe compatibility.

Features

62 tools, grouped by what you need to do

Each area below lists what works today and, just as plainly, what is partial or only possible in NWS Desktop. The server also exposes nws_capabilities, a machine-readable version of this matrix.

  • YesImplemented
  • Preview & confirmImplemented behind the safety contract
  • PartialSome parts not yet supported
  • UI-onlyNeeds NWS Desktop

Congregation data

  • YesRead 51 entity typesSynced into an owner-only local mirror; list, filter, get and describe with friendly field names. Secrets are redacted.
  • Preview & confirmCreate, update, deleteAny entity, with permission checks and stale-data detection.

NWP app publish and import

  • Preview & confirmPublish to the NWP appOptional targeted push notifications, chosen explicitly per publish.
  • Preview & confirmImport app submissionsReports, contact updates, requests, attendance and new addresses.
  • PartialNot every data type importsTerritory assignments, territory working notes, address status and completed maintenance tasks are not imported automatically.

Public witnessing

  • Preview & confirmTemplate repeat, 1–8 weeksPlus manual shift assignment and administration of locations, shifts and templates.
  • Preview & confirmImport NWP app reservations
  • YesReportsLocations utilization and per-publisher reservations, read-only.

Scheduling and duty auto-assignment

  • Preview & confirmDuty auto-assignmentUses the desktop algorithm.
  • Preview & confirmManual assignments, field-service schedulesThrough the generic change tools, with data you supply.
  • PartialOther auto-assignmentCleaning, garden care, Life and Ministry meeting and local public talks are not yet reproduced.

Backup and restore

  • YesBackups and redacted exportNWS Desktop-compatible .NWSchedulerBackup files, plus redacted JSON/CSV export. Inspect a backup by counts only.
  • Preview & confirmRestore, including partialDestructive, so it also needs overwrite_existing_data=true.
  • UI-onlyTerritory map files in backupsThey live only in the desktop’s local data folder.

Reports and print-layout data

  • YesCatalog of all 90 desktop reportsWith view access for the authenticated person.
  • YesStructured data for two layoutsS-13 territory assignment records and territory cards.
  • PartialOther 88 report typesData not implemented yet.
  • UI-onlyVisual layouts and chartsWord/PDF templates and chart images need NWS Desktop.

Attachments

  • YesList and download
  • Preview & confirmUpload and removeInformation-board attachments and territory maps (maps up to 407,200 bytes).
  • UI-onlyEmail attachmentsGenerated layouts sent through the desktop mailers.

Public-speaker sharing

  • YesList and connect to circuits
  • Preview & confirmJoin, approve, deny, leaveAnd receive congregations, speakers and outlines.
  • UI-onlySending your own data, managing circuits, speaker requestsThese need the desktop’s local settings and validation.

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 and have not been tested. Full details: capability matrix.

Safety model

It works on live data, so nothing happens by surprise

An AI agent cannot change data, publish to the NWP app, or notify anyone without an explicit, reviewable step. Reading changes nothing, and previews are read-only.

  1. Preview

    Compute the change

    A *_preview_* tool is read-only. It shows before and after records, deletions and warnings, then returns a confirmation ID.

  2. Confirm

    Review, then supply the ID

    The ID expires after ten minutes, works once, and only for its own kind of operation. Clients should show you the preview and ask.

  3. Commit

    Re-check, then write

    A *_commit_* tool reloads the inputs and refuses to write if anything changed since the preview.

Changed your mind? A *_cancel_* tool discards the plan without writing.

  • No implicit publish or notify

    Committing a change never publishes to the NWP app and never sends push notifications. Publishing is its own preview and commit, and send_notifications must be passed as true or false, with no default.

  • Permissions enforced

    Your NWS access rights are applied as in NWS Desktop. Edit, restore, publish and report-view rights are checked at commit time against freshly loaded data.

  • Stale-data checks

    A changed remote timestamp, local file, mirror or plan hash between preview and commit means the commit is rejected.

  • Destructive actions need a flag

    Restoring a backup refuses to run on preview or commit unless overwrite_existing_data=true is passed.

  • Secrets stay local

    Credentials come only from your environment. Tool output never contains passwords, PINs or tokens, and local files are owner-only.

  • Honest limits

    It cannot stop you confirming a bad change, so read the preview. Read the full safety model.

Quick start

From clone to first read in a few steps

Requires Python 3.11 or newer and an NWS congregation-sharing account. Write operations only work as far as your NWS access rights allow.

1Install

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

git clone https://github.com/dezinerdudes/nws-mcp.git
cd nws-mcp
python -m venv .venv
. .venv/bin/activate
python -m pip install .

2Set environment variables

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

VariableRequiredMeaning
NWS_CONGREGATION_IDyesYour NWS congregation ID (123-456-789 or nine digits).
NWS_CONGREGATION_PASSWORDyesThe congregation-sharing password.
NWS_EMAILyesThe email address of your NWS user. Device verification codes are sent here.
NWS_VENDOR_CONFIG_PATHyesPath to the NWS vendor configuration file (JSON).
NWS_CONGREGATION_PINfor NWP app toolsThe congregation PIN used by the NWP app.
NWS_STATE_DIRnoWhere the local mirror, tokens and pending confirmations are stored. Default: ~/.local/share/nws-mcp.

Vendor configuration file required. 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.

3Add it to your MCP client

For Claude Code, one command:

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 as a project .mcp.json (do not commit real credentials). Claude Desktop accepts the same entry in claude_desktop_config.json.

{
  "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"
      }
    }
  }
}

4First steps

Run nws_status to check that the configuration loads, then nws_authenticate. On a new device NWS emails a verification code; pass it to nws_verify. Then nws_sync fills the local mirror, and nws_list and nws_get read it. The README walks through changes and publishing.