loop-mcp

MCP server that lets Claude read and write Microsoft Loop pages — on your own Loop login, from your own machine.

Tool	Action
loop_get_page	Read a page (by URL) as Markdown
loop_list_pages	List the top-level pages of a workspace
loop_create_page	Create a page from Markdown
loop_edit_page	Append to / replace a page

What's an MCP?

MCP stands for Model Context Protocol. Think of it as a plug-in that gives Claude the ability to talk to a specific tool — in this case, Microsoft Loop. You install it once; after that, it works in every conversation.

Why a browser? (architecture)

Microsoft Loop has no API for creating or editing pages (confirmed by Microsoft, 2026). Reading via the Graph API exists but requires an Azure app registration + admin consent + SharePoint Embedded guest registration — a governance bottleneck. So this MCP drives the Loop web app itself in a dedicated Chrome window that you sign into:

• Read — opens the page, extracts the rendered content, converts to Markdown.
• Write — pastes Markdown; Loop converts it into native blocks (headings, lists, tables, checklists…).

Everything runs as you: the tool can only see and touch what your own Loop account can. No shared secrets, no elevated permissions, nothing leaves your machine.

Trade-offs to know: the dedicated browser window must be open and signed in while you use the tools, and Microsoft's security policy will typically ask you to sign in again each day (same as the regular Loop website).

Install (one command)

git clone https://github.com/2mattias/loop-mcp.git && cd loop-mcp && ./install.sh

The installer checks prerequisites (installs python3.12/pipx via Homebrew if missing), installs the package, downloads the browser, registers the MCP with Claude Code, and opens the sign-in window.

The only manual step: sign into Loop in the window that opens (password + token PIN). Let Chrome save your password and answer Yes to "Stay signed in?" — future days become autofill + PIN.

Then restart Claude Code and try: "read this Loop page: <paste a Loop URL>".

Daily use

Keep the "Chrome for Testing" window open (signed into Loop) whenever you use the Loop tools. If you closed it, reopen with:

<path-to-repo>/scripts/launch-chrome-debug.sh

If a Loop tool suddenly fails with a sign-in page, that's Microsoft's daily re-authentication — sign in again in that window and retry.

For AI assistants (Claude)

SKILL.md contains the full operating manual: tool reference, Markdown formatting rules for Loop (what renders well, what to avoid), safety rules for creating/editing pages, and an ordered troubleshooting matrix for connection problems. Install it as a Claude Code skill to get /loop-page:

mkdir -p ~/.claude/skills/loop-page
cp SKILL.md ~/.claude/skills/loop-page/SKILL.md

Configuration (environment variables)

Variable	What it is
LOOP_CDP_URL	auto (default) discovers the debug Chrome; a URL like http://localhost:9222 attaches explicitly.
LOOP_CDP_PORTS	Ports scanned in auto mode (default 9222,9223,9224).
LOOP_DEFAULT_WORKSPACE_URL	Default workspace for create/list (optional — copy your workspace URL from the browser).
LOOP_PROFILE_DIR	Alternative mode: dedicated Playwright profile instead of CDP attach.
LOOP_HEADLESS	true for headless (profile mode only).
LOOP_BROWSER_CHANNEL	Profile mode: chrome for system Chrome; empty = bundled Chromium.

The launcher script honors LOOP_CDP_PORT (default 9222) and LOOP_CHROME_DEBUG_DIR (default ~/.loop-mcp/chrome-debug).

CLI (test without Claude)

loop-mcp read "<page_url>"
loop-mcp list --workspace-url "<workspace_url>"
loop-mcp create "Page title" --stdin < content.md
loop-mcp edit "<page_url>" --mode append --stdin < addendum.md

Manual registration (if the installer couldn't)

claude mcp add loop --env LOOP_CDP_URL=auto \
  -- ~/.local/pipx/venvs/loop-mcp/bin/python -m loop_mcp.mcp

Or in a project's .mcp.json:

{
  "mcpServers": {
    "loop": {
      "type": "stdio",
      "command": "/Users/<you>/.local/pipx/venvs/loop-mcp/bin/python",
      "args": ["-m", "loop_mcp.mcp"],
      "env": { "LOOP_CDP_URL": "auto" }
    }
  }
}

Troubleshooting (quick)

Symptom	Fix
"Could not attach to Chrome"	Run scripts/launch-chrome-debug.sh and sign in
Tool returns the Loop marketing page / "Sign in"	Daily re-auth — sign in again in the debug window
"Browser context management is not supported"	You pointed it at your everyday Chrome — use the launcher script instead
Tools missing in Claude	claude mcp list should show loop; re-register and restart Claude Code

The full ordered troubleshooting matrix (for you or your AI) is in SKILL.md.

Uninstall

claude mcp remove loop
pipx uninstall loop-mcp
rm -rf ~/.loop-mcp ~/.claude/skills/loop-page

Requirements

• macOS (Linux best-effort), Claude Code
• Python 3.12 + pipx (auto-installed via Homebrew if missing)
• A Microsoft 365 account with Loop access

Status / validation

All selectors and flows validated live against the Loop web app (2026-07-21): read, list, create (end-to-end), and the paste-to-blocks conversion. Selectors are role/name-based (accessibility tree) — the most stable option — but a Loop UI redesign can still break them; fixes land in this repo.

License

MIT