open-worship-app-mcp
Official# open-worship-app-mcp
The MCP server of the [Open Worship App](https://www.openworship.app), for
any AI agent that speaks the Model Context Protocol (Claude Code, Claude
Desktop, Cursor, VS Code, ...). Start the app, add this server to your
client, and the agent can see and drive the app the way its own built-in
help assistant does: find a control by its words, press it, read what is on
the projector, put a verse up, look up the manual, edit a song or a slide
document with every change backed up for undo.
It is the same server the app runs inside itself for its 🤖 help window --
76 tools: Chrome DevTools' browser tools aimed at the running app
plus the app's own `owa_*` tools -- with the same firewall in front.
Version 2026.11.15 follows the app's 2026.11.15 (npm writes no leading
zero).
## Quick start
1. Install and open the Open Worship App. **Settings -> AI Providers ->
Enable AI features** must be on (it is unless someone turned it off); with
it off the app opens no door for an agent.
2. Add the server to your client:
```sh
claude mcp add owa-devtools -- npx -y open-worship-app-mcp
```
or, for a client configured with JSON:
```json
{
"mcpServers": {
"owa-devtools": {
"command": "npx",
"args": ["-y", "open-worship-app-mcp"]
}
}
}
```
3. Ask your agent something like _"What is on the projector right now?"_ or
_"Open the Bible Reader at John 3:16"_.
Nothing to configure: the server finds the running app by itself. Every app
publishes how to reach it in `<temp folder>/open-worship-app-cdp/<pid>.json`;
the server reads the newest one on every call, so it can start before the
app and follows a restart. Requires Node.js >=22.12.0.
### No Node.js on that computer?
The app carries the SAME server as a single executable: **Settings -> Others
-> Extra Binaries**, install (or update) the pack, and the **AI agents (MCP)**
picker shows, for the AI program you choose in it, the command or settings
text to paste into it, with a **Copy** button. The executable runs the very
files this package runs; the build holds the two to the same answers, tool
for tool.
### Choosing an app
| Setting | What it does |
| ----------------------- | -------------------------------------------------------------------------- |
| (none) | One app running: drives it. Several: lists them and drives none until the agent asks you and calls `owa_choose_app` with the pid you pick. |
| `OWA_CDP_TARGET=dev` | Only a development app (`npm run dev`), following its restarts. |
| `OWA_CDP_TARGET=prod` | Only an installed (packaged) app. |
| `OWA_CDP_PORT=<port>` | That debugging port or nothing -- a pin, never a preference. |
The server is made from one app version and the tools follow that version's
words and panels: `owa_app_state` carries `versionCheck`, and when the two
differ it says which to update. The server's `initialize` instructions tell the
agent both things.
For a client that can only be pointed at one fixed URL,
`npx open-worship-app-mcp --bridge --listen=9223` forwards that port to
wherever the app is.
## What an agent may do
**The assistant may point, the human presses.** Every window of the app runs
with Node.js integration, so the server's firewall refuses and hides
`evaluate_script`, `take_heapsnapshot` and `upload_file`; allows navigation
only to the app's own pages; refuses a press on anything that cannot be
undone (delete, discard, clear all, sign out ... in every language the app is
shown in, read on the control itself as well as on the words); leaves the
app's own questions (confirm, alert) to the person; rations acting calls to 25
a minute, web reads and removals to 10 every five minutes each; and scrubs
provider keys and tokens out of every result. Every change to a document is
backed up first and carries an `undoId`; `owa_undo` takes it back.
`OWA_MCP_FIREWALL=off` turns the firewall off. It is an environment variable
only, so nothing an agent sends can reach it; do not set it to make a task
easier.
## Tools
### The app's own tools (47)
| Tool | What it does |
| ---- | ------------ |
| `owa_bible_xml` | Bibles from XML. `check` a `url` (no link: https://github.com/Beblia/Holy-Bible-XML-Format, the language in `find`): a page answers its .xml files; a file a `draftId` and choices to pick -- `keys`, `locales`, `digits`, `... |
| `owa_choose_app` | Which running Open Worship app to work with, when more than one is running. |
| `owa_help_search` | Search this app's own knowledge for how to do something in it -- FIRST for any "how do I", "where is" or "what does X do" question, before poking at the UI. |
| `owa_list_questions` | The questions this app is prepared to answer, grouped by the page and panel they belong to, each carrying the manual recipe, control and keystroke that answers it. |
| `owa_tran` | What a button is CALLED on this user’s screen when the app runs in another language: pass the English label as the manual writes it, get back the words printed on that control, and name it with those. |
| `owa_help_page` | Read one knowledge document by the id an owa_help_search hit carries (e.g. |
| `owa_app_state` | What the running app is doing right now: every live instance, its open windows, and one window's page, language, theme and visible tabs. |
| `owa_list_screens` | What is on the projector right now. |
| `owa_present_bible` | Put a Bible passage on the projector by its REFERENCE -- "John 3:16", "Psalm 23:1-6" -- and answer with what is on the screen now. |
| `owa_foreground` | Start or stop any foreground extra on the projector -- countdown, stopwatch, clock, marquee (top/bottom), quick text, message, long text, video/image/web show, camera, another screen -- through its own Foreground panel: ... |
| `owa_screenshot` | A picture of what the operator is looking at right now: the app window, or a projector screen by id. |
| `owa_read_website` | Read a page on the public web -- its text, optionally its links and a picture of it. |
| `owa_lyric_validate` | Check song text in Open Lyric notation -- the Lyric Editor's format: every mistake with its line, its section and what to write instead, then what the song IS (title, key, tempo, sections, play order). |
| `owa_lyric_file` | Look at and change the user's songs (Open Lyric documents). |
| `owa_slide_file` | Look at and change the user's slide documents. |
| `owa_lyric_edit` | Change one of the user's songs part by part. |
| `owa_slide_edit` | Change one of the user's slide documents. |
| `owa_note_edit` | Change the user's Bible note attached here, in its own window as the person sees it. |
| `owa_presenting_flow_edit` | Change one of the user's presenting flows (a service's running order). |
| `owa_foreground_edit` | Change a foreground component through its own panel: a SESSION of it (a saved set-up: its words and its look). |
| `owa_screen_edit` | The screens' own controls, as each Mini Screen card and the Bible text panel set them. |
| `owa_bible_item` | The user's saved Bible passages (the Bibles list; the Reader keeps its own). |
| `owa_find_verse` | Find in a Bible installed here a verse the user half-remembers, a story, or every verse with a word. |
| `owa_lookup_record` | Read a Bible person or place from the names lookup (drawn from the KJV), or a Bible passage. |
| `owa_resource_file` | The user's Resources files: study PDFs, notes, links and pictures named by book and chapter (LUK.6.pdf is Luke 6, LUK.0 its introduction). |
| `owa_bible_suggest` | The chat box's input aid, read by the WINDOW as a person types -- not by you. |
| `owa_bible_note` | The user's Bible notes. |
| `owa_presenting_flow` | The user's run sheets (presenting flows): the order of a service. |
| `owa_media_file` | The user's Background files by `kind`: pictures, clips, tracks (the Images / Videos / Audios tabs), web pages (Webs), and the Documents folder's files (`document`: import a PDF, PowerPoint, Word, song or slide file from ... |
| `owa_undo` | Put back a change made through these tools -- a song, slide document, slide, note, saved passage, run sheet or media file that was deleted, changed, renamed or created. |
| `owa_language` | The app languages. `list`: the installed ones and the catalog's others. |
| `owa_pick_element` | Ask the user to POINT at a control: an outline follows their mouse and the next thing they click is answered with -- its words, the panel it is in, whether it is on screen, and a selector for it. |
| `owa_highlight_selector` | Ring the exact element a CSS selector names, for four seconds, in the real window. |
| `owa_hide_screens` | Hide one presentation screen by id, or every screen when no id is given. |
| `owa_goto_page` | Switch the main app window to one of its pages. |
| `owa_find_ui` | Find a control in the app by its visible text or tooltip, and say where it is on screen (plus which component renders it, in dev). |
| `owa_list_ui` | List the controls actually on screen in a window right now -- every visible button, link, box and dropdown with the words written on it, the panel it is in and where. |
| `owa_click` | Click a control in the app, found by the exact words written on it -- pass a list of candidate labels and the first one on screen wins. |
| `owa_type` | Type text into a box in the app, found by its label, placeholder or the text already in it -- e.g. |
| `owa_press_key` | Press a keyboard shortcut in the app window: "F5", "Ctrl+S", "Escape", "ArrowRight", "Space", "Shift+Enter". |
| `owa_drag` | Drag one control onto another, both found by their labels -- a Documents row into a presenting flow, a slide onto another slide, a background onto a slide card. |
| `owa_drop_files` | Drop real files or folders from the disk onto a control found by its label -- a picture onto the slide canvas, a song file onto the Documents list, a folder onto Resources. |
| `owa_scroll` | Scroll a list in the app to reach rows that are not on screen -- the long lists are windowed, so a row past the fold matches nothing until the list is scrolled. |
| `owa_menu` | The app's menu bar (File, Edit, View, Tools, Window, Help). |
| `owa_guide_start` | Walk the user through a task IN THE APP WINDOW: a numbered card in the corner, each step's control ringed in red; the user presses Next or just does the step. |
| `owa_guide_step` | Move a running guide: `next`, `back`, `stop`, `goto` with a step number, or `do` -- which performs the current step in the app (the same thing the card's **Do it** button does) and then moves on. |
| `owa_guide_status` | Where the user is in a running guide: step number, its text, whether the control this step names was found on screen, the closest labels that ARE on screen when it was not (`nearMisses` -- restart the guide with one of t... |
### Browser tools, aimed at the app's windows (29)
| Tool | What it does |
| ---- | ------------ |
| `click` | Clicks on the provided element |
| `close_page` | Closes the page by its index. |
| `drag` | Drag an element onto another element |
| `emulate` | Emulates various features on the target page. |
| `fill` | Type text into an input, text area or select an option from a <select> element. |
| `fill_form` | Fill out multiple form elements (inputs, selects, checkboxes, radios) at once. |
| `get_console_message` | Gets a console message by its ID. |
| `get_css_styles` | Retrieve matched CSS rules, inline styles (element.style), inherited styles, custom properties, and cascade wrappers (@layer, @media, @container, @scope) for an element identified by its UID. |
| `get_network_request` | Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel. |
| `handle_dialog` | If a browser dialog was opened, use this command to handle it |
| `hover` | Hover over the provided element |
| `lighthouse_audit` | Get Lighthouse scores, failing audits, and the DOM nodes they flag for accessibility, SEO, best practices, and agentic browsing. |
| `list_console_messages` | List all console messages for the target page since the last navigation. |
| `list_network_requests` | Lists the most recent requests for the target page since the last navigation. |
| `list_pages` | Get a list of pages open in the browser. |
| `navigate_page` | Go to a URL, or back, forward, or reload. |
| `new_page` | Open a new tab and load a URL. |
| `performance_analyze_insight` | Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording. |
| `performance_start_trace` | Start a performance trace on the target webpage. |
| `performance_stop_trace` | Stop the active performance trace recording on the target webpage. |
| `press_key` | Press a key or key combination. |
| `resize_page` | Resizes the page's window so that the page has specified dimension |
| `screencast_start` | Starts recording a screencast (video) of the target page. |
| `screencast_stop` | Stops the active screencast recording on the target page. |
| `select_page` | Select a page as a context for future tool calls. |
| `take_screenshot` | Take a screenshot of the page or element. |
| `take_snapshot` | Take a text snapshot of the target page based on the a11y tree. |
| `type_text` | Type text using keyboard into a previously focused input |
| `wait_for` | Wait for the specified text to appear on the selected page. |
## JavaScript / TypeScript API
The package exports the same server as functions (ESM, typed by
`index.d.mts`; on Node 22.12 and later `require()` works too):
```ts
import {
createOwaMcpServer,
findDrivenInstance,
listOwaAppInstances,
runOwaMcpStdioServer,
type OwaAppInstance,
} from 'open-worship-app-mcp';
// Which apps are running? (newest first; the app's own door token is never
// handed out)
const apps: OwaAppInstance[] = listOwaAppInstances();
console.log(apps.map((app) => `${app.version} on port ${app.port}`));
console.log(findDrivenInstance()); // the one a server started now would drive
// Serve it over this process's stdin/stdout, exactly as the command does:
await runOwaMcpStdioServer();
// ... or put it behind a transport of your own (any MCP SDK transport):
const { server } = await createOwaMcpServer();
await server.connect(myTransport);
```
| Export | What it is |
| ----------------------------------- | ------------------------------------------------------------------ |
| `listOwaAppInstances()` | Every running app, newest first. |
| `findDrivenInstance()` | The app a server started now would drive, or `null`. |
| `resolveAppBrowserUrl()` | Its debugging address (`http://127.0.0.1:1` when none runs). |
| `createOwaMcpServer(options?)` | The MCP server, not yet connected: `{ server }`. |
| `runOwaMcpStdioServer(options?)` | The command's own body: serves on stdin/stdout. |
| `runOwaMcpBridge({ listenPort })` | The `--bridge` forwarder: `{ port, close }`. |
| `redactSecrets(text)` | The firewall's scrubber for keys and tokens. |
| `OWA_CDP_INFO_DIR_PATH` | Where the running apps publish themselves. |
Finding an app reads a few small files; the server itself (Chrome DevTools
MCP and puppeteer) loads only when one is asked for.
## What is in the package
| Folder | What |
| ---------------------------- | ------------------------------------------------------------------ |
| `tools/owa-devtools-mcp/` | The server, its tests and the question corpus it answers from. |
| `electron-build/knowledge/` | The knowledge bundle: the user manual and the developers' notes. |
| `docs/manual-sources/` | The manual's pages. |
| `src/lang/data/` | English's tables and every language package's text (dictionary, assistant facts, questions, translated manual). |
| `.claude/skills/owa-robot-test/` | The app's robot end-to-end test, a Claude Code skill: QA of the live app through this server. |
| `docs/test-paths/coverage-matrix.md` | What that robot test covers. |
The folders mirror the app's own repository, because every module finds its
files from there. No credential, no binary, no file git ignores; a home
folder in a note is written `~`.
## Tests
```sh
npm install
npm test
```
The server's unit tests (154 files), run as the app runs them. For
live testing, open this folder in Claude Code (its `.mcp.json` names the
server `owa-devtools`, as the skill expects), start the app, and ask for
`/owa-robot-test`.
## Source and license
Built from [OpenWorshipApp/open-worship-app-dt](https://github.com/OpenWorshipApp/open-worship-app-dt)
at commit `cad84e491773` by `npm run build-open-worship-app-mcp`; change it
there, not here. GPL-2.0, see `LICENSE.txt`.
TDQS
Scored across 76 tools
Two parallel UI-driving surfaces exist: the generic Playwright-style tools (click, fill, hover, press_key, drag, take_snapshot) and the app-specific ones (owa_click, owa_type, owa_press_key, owa_drag, owa_list_ui, owa_find_ui). An agent must decide which family to use for the same action, and nothing in the names settles it. There is also heavy overlap within the domain: owa_lyric_file vs owa_lyric_edit, owa_slide_file vs owa_slide_edit, owa_presenting_flow vs owa_presenting_flow_edit, owa_foreground vs owa_foreground_edit, plus owa_bible_item/owa_bible_note/owa_bible_xml/owa_lookup_record.
Names are uniformly snake_case and most follow verb_noun (owa_present_bible, owa_create... , list_console_messages, navigate_page). But the owa_ prefix is applied inconsistently relative to the unprefixed browser tools, and many domain tools are noun-only or compound (owa_app_state, owa_menu, owa_help_page, owa_lyric_file, owa_bible_xml). Readable, but the convention breaks down across the set.
76 tools is far past what this domain justifies, and a large share are duplicates of each other (generic page automation alongside app-specific equivalents, plus _file/_edit pairs for songs, slides, notes, flows, and foregrounds). The surface reads like two servers merged into one rather than a well-scoped set.
Coverage is genuinely broad: CRUD for songs, slides, notes, Bibles, saved passages, media, run sheets, screens, plus undo, help/knowledge search, language, screenshots, and guided walkthroughs. Remaining gaps are minor and mostly workaround-able rather than dead ends.