# nws-mcp

An unofficial [Model Context Protocol](https://modelcontextprotocol.io) (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](#features)
- [Safety model](#safety-model)
- [Requirements](#requirements)
- [Install](#install)
- [Configuration](#configuration)
- [MCP client setup](#mcp-client-setup)
- [First steps](#first-steps)
- [Development](#development)
- [Documentation](#documentation)
- [License](#license)

## Features

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

| Area | What you can do |
| --- | --- |
| Connection | Authenticate with congregation sharing, including emailed device verification; authenticate the NWP app bridge; value-free status. |
| Data access | Sync 51 entity types into an owner-only local mirror; list, filter, get and describe entities with friendly field names; secrets redacted. |
| Changes | Create, update or delete any entity with permission checks and stale-data detection. |
| NWP app | Publish pending changes to the NWP app, optionally with NWS Desktop's targeted push notifications; import pending app submissions (reports, contact updates, requests, attendance, new addresses). |
| Scheduling | Duty auto-assignment with the desktop algorithm; manual assignments and field-service schedules through the generic change tools. |
| Public witnessing | Repeat templates over 1-8 weeks; assign shift positions; administer locations, shifts and templates; import reservations made in the NWP app; utilization and per-publisher reports. |
| Files | Redacted JSON/CSV export; NWS Desktop-compatible `.NWSchedulerBackup` backups; inspect and restore backups, including partial restores. |
| Attachments | List, download, upload and remove information-board attachments and territory maps. |
| Print layouts | Catalog of all 90 desktop reports with view access; structured data for S-13 territory assignment records and territory cards. |
| Public-speaker sharing | List and connect to circuits; request to join, approve, deny, leave; receive congregations, speakers and outlines. |
| Capabilities | `nws_capabilities` returns a machine-readable matrix of what is supported, guarded or UI-only. See [docs/capabilities.md](docs/capabilities.md). |

## Safety model

Summary (details in [docs/safety.md](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](#configuration)).

## Install

```sh
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.

| Variable | Required | Meaning |
| --- | --- | --- |
| `NWS_CONGREGATION_ID` | yes | Your NWS congregation ID (`123-456-789` or nine digits). |
| `NWS_CONGREGATION_PASSWORD` | yes | The congregation-sharing password. |
| `NWS_EMAIL` | yes | The email address of your NWS user. Device verification codes are sent here. |
| `NWS_VENDOR_CONFIG_PATH` | yes | Path to the NWS vendor configuration file (JSON). |
| `NWS_CONGREGATION_PIN` | for NWP app tools | The congregation PIN used by the NWP app. Spaces, dashes and underscores are ignored. |
| `NWS_PERSON_PIN` | no | Reserved; currently unused. |
| `NWS_STATE_DIR` | no | Where the local mirror, tokens and pending confirmations are stored. Default: `~/.local/share/nws-mcp`. |

**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

```sh
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):

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

### Claude Desktop

Add the same entry to `claude_desktop_config.json` (Settings, Developer,
Edit 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",
        "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

```sh
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](docs/tools.md): every tool, its parameters and behaviour.
- [docs/safety.md](docs/safety.md): the safety model.
- [docs/capabilities.md](docs/capabilities.md): the capability matrix,
  including unsupported and UI-only items.
- [docs/design/](docs/design/): design notes.

## License

[MIT](LICENSE). Copyright 2026 DezinerDudes.

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