# 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)

```bash
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:

```bash
<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`:

```bash
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)

```bash
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)

```bash
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`:

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

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

## Requirements

- macOS (Linux best-effort), [Claude Code](https://claude.com/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