# chrome-cookies-mcp

An MCP (Model Context Protocol) server that reads cookies for a specified
domain from a running Chrome instance, via the Chrome **DevTools Protocol (CDP)**.

It returns cookies already decrypted by Chrome (no SQLite decryption, no
App-Bound-Encryption handling), in `cookies.txt` (Netscape), JSON, or
`Cookie:`-header format.

## How it relates to the "Get cookies.txt LOCALLY" extension

That extension uses the privileged `chrome.cookies.getAll({ domain })` API,
which only works *inside* an extension. A standalone MCP server can't call it,
so this project gets the same decrypted cookies a different way: it attaches to
Chrome over CDP and calls `Storage.getCookies`, then applies the same
domain-matching and the same Netscape/JSON/header serialization the extension
used.

## Requirement: launch Chrome with a debug port

CDP only works against a Chrome started with `--remote-debugging-port`. Chrome
allows just one process per profile directory, so if your normal Chrome is
already running you must **close it first**, then relaunch with the flag (still
your real profile, same logins/cookies):

```
chrome.exe --remote-debugging-port=9222 \
  --user-data-dir="C:\Users\<you>\AppData\Local\Google\Chrome\User Data" \
  --profile-directory=Default \
  --remote-allow-origins=*
```

Helper:

```
npm run launch-chrome      # close your main Chrome first
```

Verify the port is live: open <http://127.0.0.1:9222/json/version>.

## Install

```
npm install
cp .env.example .env.local   # then edit .env.local for your machine
```

## Local configuration (`.env.local`)

Machine-specific settings (paths, port, profile) live in **`.env.local`**, which
is gitignored and never committed. Copy `.env.example` to `.env.local` and edit.
Values already set in the real environment — or in an MCP client's `env`
block — override the file, so the same code runs unchanged on any machine.

Environment variables:

| Var                    | Default                                   | Meaning                          |
| ---------------------- | ----------------------------------------- | -------------------------------- |
| `CHROME_CDP_HOST`      | `127.0.0.1`                               | CDP host                         |
| `CHROME_CDP_PORT`      | `9222`                                    | CDP remote-debugging port        |
| `CHROME_PATH`          | auto-detected                             | chrome.exe path (launcher only)  |
| `CHROME_USER_DATA_DIR` | OS default profile dir                    | profile dir (launcher only)      |
| `CHROME_PROFILE`       | `Default`                                 | profile name (launcher only)     |

## Run

```
npm start
```

## Tools

### `get_cookies`
Get cookies for a domain.
- `domain` (required): `"example.com"`, `".github.com"`, or a full URL like `"https://example.com/path"`.
- `format`: `netscape` | `json` | `header` (default `json`).
- `name` (optional): only the cookie with this exact name.
- `path` (optional): only cookies with this exact path.

Domain matching follows `chrome.cookies.getAll`: the query matches a cookie
whose host equals the domain or is a sub/parent-domain of it.

### `list_domains`
List all distinct cookie domains in the running Chrome with counts.
- `filter` (optional): case-insensitive substring of the domain name.

## Register with an MCP client

Example (`claude` / Claude Code `.mcp.json` style):

```json
{
  "mcpServers": {
    "chrome-cookies": {
      "command": "node",
      "args": ["/absolute/path/to/chrome-cookies-mcp/src/index.mjs"],
      "env": { "CHROME_CDP_PORT": "9222" }
    }
  }
}
```

## Test

```
npm run launch-chrome           # or launch any Chrome with --remote-debugging-port=9333
CHROME_CDP_PORT=9333 node test/smoke.mjs
```

## Security note

This server exposes your browser's cookies — including session tokens — to any
MCP client connected to it. Cookies are sensitive credentials. Run it only
locally and only with clients you trust. The CDP debug port itself is also a
powerful local interface; do not expose it beyond `127.0.0.1`.