Skip to main content
Glama

chrome-session-mcp

An MCP server that lets an AI agent (Claude Code, Claude Desktop, Cursor, or any MCP client) use the internal web apps you are already logged in to in Google Chrome: Grafana, Slack, Jenkins, SonarQube, Confluence, Kibana, or any site that authenticates with a browser cookie.

There are no API tokens, OAuth apps, or service accounts to set up. The server reads your own Chrome session cookies, so the agent sees exactly what you see and nothing more. When a session expires, it opens Chrome on the login page, waits for you to log in, and then retries the call.

agent ──MCP──▶ chrome-session-mcp ──HTTPS + your cookies──▶ grafana.acme.internal
                     │                                      slack.com
                     └─ reads ~/…/Chrome/<profile>/Cookies    jenkins.acme.internal …
  • Standard library only. Python 3.9+ and the system openssl. Nothing to pip install at run time.

  • Config-driven. Name your instances (grafana-prod, grafana-staging, …). Tools appear only for the connector types you configure.

  • Read-only by default. Write tools (post to Slack, edit Confluence, POST to an API) are hidden until you set "allow_write": true on that connector.

  • Extensible. Add a private connector for your own internal tool in about 40 lines (see Custom connectors).

Platforms: macOS and Linux. Windows is not supported: Chrome on Windows encrypts cookies with app-bound encryption, which another process cannot decrypt.

Contents

Related MCP server: Browser MCP

Quick start

1. Install. Any of these work:

pipx install chrome-session-mcp            # or: uv tool install chrome-session-mcp
# or run it straight from a checkout, with nothing installed:
git clone https://github.com/tix-tarsidi-danesh/chrome-session-mcp && export PYTHONPATH=$PWD/chrome-session-mcp/src

2. Write a config at ~/.config/chrome-session-mcp/config.json (or point CHROME_SESSION_MCP_CONFIG at another path):

{
  "connectors": {
    "grafana": {"type": "grafana", "base_url": "https://grafana.acme.internal"},
    "slack":   {"type": "slack", "workspace": "acme.slack.com"},
    "jenkins": {"type": "jenkins", "base_url": "https://jenkins.acme.internal",
                "job_path": "job/team/job/checkout-service"}
  }
}

examples/config.example.json shows every built-in type.

3. Register the server with your MCP client.

Claude Code:

claude mcp add chrome-session -- chrome-session-mcp
# from a checkout instead:
claude mcp add chrome-session -e PYTHONPATH=/path/to/chrome-session-mcp/src -- python3 -m chrome_session_mcp

Claude Desktop, Cursor, and other clients that use a JSON file:

{
  "mcpServers": {
    "chrome-session": {
      "command": "chrome-session-mcp",
      "env": {"CHROME_SESSION_MCP_CONFIG": "/Users/me/.config/chrome-session-mcp/config.json"}
    }
  }
}

4. Try it. Ask the agent to "call auth_status". The first call that reads cookies on macOS shows a Keychain prompt for Chrome Safe Storage. Choose Always Allow so it is not asked again. The server reads that key once per process and keeps it in memory.

How login recovery works

Every connector has a cheap probe request that succeeds only with a valid session (for example Grafana GET /api/user). When a tool call is rejected as logged out, the server does this:

  1. It opens Chrome on the connector's login_url, in the profile the cookies came from. It opens the page at most once every 2 minutes per connector, so a retrying agent cannot fill your screen with tabs.

  2. Every 3 seconds it re-reads Chrome's cookie database and runs the probe. Chrome writes new cookies to disk with a delay of up to about 30 seconds after the login, so the server polls instead of waiting a fixed time.

  3. When the probe passes, it retries the original call once. If the wait runs out (default 180 s), the tool returns an error that tells the agent to retry after you log in.

"Logged out" is recognized in these forms:

Answer

Typical source

The response ends on accounts.google.com, or a 3xx redirect to a login page

Google IAP, most SSO front doors

302 with Auth Cookie is invalid / Cookie Expired in the body

Google IAP answering a POST

401

Most APIs

403 plus a redirect to /securityRealm/commenceLogin

Jenkins with an SSO realm

api/authentication/validate returns valid: false

SonarQube

The current user is anonymous

Confluence

invalid_auth, not_authed, token_expired, …

Slack

Grafana is a special case. On a 401 the server first asks Grafana to rotate its own session token (POST /api/user/auth-tokens/rotate) and only opens Chrome if that fails.

Set CHROME_SESSION_MCP_NO_BROWSER=1 to never open Chrome (for CI, or a headless machine). The tools then report the expiry and stop.

Configuration

{
  "settings": {
    "login_wait": 180,          // seconds to wait for a login; 0 = never wait
    "open_browser": true,       // false = report expiry, never open Chrome
    "max_inline": 60000,        // larger tool results are written to a file instead
    "chrome_profile": null,     // e.g. "Profile 1"; default = the profile with the most cookies for the host
    "chrome_user_data": null    // Chrome's user-data dir, if not the default
  },
  "plugin_paths": ["~/acme-connectors"],          // added to sys.path
  "plugins": ["acme_connectors.feature_flags"],   // imported at start; they register their own types
  "connectors": {
    "<instance name>": {"type": "<type>", "base_url": "https://…", "…": "…"}
  }
}

Settings every connector accepts:

Key

Meaning

type

Connector type (see below). Required.

base_url

Site root, e.g. https://grafana.acme.internal. Required for all types except slack.

login_url

Page to open when the session expires. Default: a type-specific page on base_url.

probe

Path of a GET that succeeds only when logged in. Overrides the type's default.

cookie_host

Read cookies for this host instead of base_url's host (e.g. a parent domain).

headers

Extra static headers sent with every request.

allow_write

true makes this instance's write tools available. Default false.

description

Free text, shown by list_connectors to help the agent pick an instance.

A broken entry (unknown type, unknown key, bad URL) does not stop the server. The other connectors keep working, and list_connectors reports the error.

Environment variables (these override the config file):

Variable

Meaning

CHROME_SESSION_MCP_CONFIG

Config file path.

CHROME_SESSION_MCP_CACHE

Cache directory (default ~/.cache/chrome-session-mcp).

CHROME_SESSION_MCP_LOGIN_WAIT

Seconds to wait for a login.

CHROME_SESSION_MCP_NO_BROWSER=1

Never open Chrome.

CHROME_PROFILE, CHROME_USER_DATA

Pin the Chrome profile / user-data directory.

CHROME_SAFE_STORAGE_PASSWORD

Linux: the keyring password, if secret-tool cannot find it.

Connectors and tools

Each tool of a typed connector takes an instance argument. It is optional when only one instance of that type is configured, or when the tool takes a url argument (the server then picks the instance by the URL's host). Tools marked ✎ are write tools and appear only on instances with "allow_write": true.

Always available

Tool

What it does

list_connectors

The configured instances and any config errors. Call it first. Without a config file it returns setup help.

auth_status

Which instances have a working session right now. Never opens a browser.

login

Open Chrome on an instance's login page and wait until the session works.

open_in_browser

Open a URL in your Chrome (in the profile that is logged in to it), e.g. to show you a failing build.

grafana: {"type": "grafana", "base_url": "…"}

Tool

What it does

grafana_resolve

Follow a /goto/ short link: dashboard URL, uid, variables, time range.

grafana_dashboard

A dashboard's variables and panels. The full JSON is written to a file.

grafana_run_panel

Run a panel's queries and return last / min / max / avg per series.

grafana_get

GET any Grafana HTTP API path.

slack: {"type": "slack", "workspace": "acme.slack.com"} (or "team_id": "T0123ABCD")

Slack's web client needs the d cookie and an xoxc- session token, which Slack keeps in Chrome's localStorage. The connector reads both. If you are signed in to several workspaces, it keeps the token whose auth.test matches workspace / team_id.

Tool

What it does

slack_channels

List channels (cached for 24 h), filtered by a regex.

slack_history

A channel's messages in a time window.

slack_thread

A thread, from a message link or channel + ts.

slack_search

Slack search syntax, e.g. in:#incidents timeout after:2026-09-01.

slack_user

A user's profile by ID or email.

slack_post ✎

Post a message or a thread reply as you.

jenkins and sonarqube

"ci":    {"type": "jenkins", "base_url": "https://jenkins.acme.internal",
          "job_path": "job/team/job/checkout-service", "sonar": "sonar", "sonar_project": "checkout-service"},
"sonar": {"type": "sonarqube", "base_url": "https://sonar.acme.internal"}

job_path is the default multibranch job, and the tools also accept a Blue Ocean or classic Jenkins URL. sonar names a sonarqube instance. When it is set, jenkins_pr_status includes that PR's quality gate.

Tool

What it does

jenkins_pr_status

Every pipeline stage with status and duration, the log tail of each failed step, and the Sonar quality gate.

jenkins_console_log

A build's console output: the last N lines, or grep matches with context.

sonar_quality_gate

Quality-gate status and conditions for a PR, a branch, or the main branch.

confluence: {"type": "confluence", "base_url": "https://acme.atlassian.net"}

For Server / Data Center, add "api_path": "/rest/api". Page bodies are moved as storage-format XHTML through local files, never as Markdown and never inline. A Markdown round-trip breaks embedded images, and a long page's body can pass 250,000 characters, which is too large for a tool argument.

Tool

What it does

confluence_get_page

Write a page's body to a file. Return title, version, size, and counts of images / macros / comment anchors.

confluence_list_attachments

A page's attachments.

confluence_update_page ✎

Replace the body from a file. Refuses the update when the page changed since you read it (expected_version), when the body shrinks by more than half, or when images / macros / comment anchors would be lost. Backs up the old body first.

confluence_create_page ✎

Create a page.

confluence_upload_attachment ✎

Upload a file, e.g. a rendered diagram, to embed it.

confluence_set_appearance ✎

Full-width or fixed-width layout.

kibana: {"type": "kibana", "base_url": "…"}

Searches use Kibana's own search API (/internal/search/ese), so they work for anyone who can open Discover. Tested against Kibana 7.17.

Tool

What it does

kibana_resolve

Follow a /goto/ short link: index pattern, query, time range.

kibana_indices

List index patterns.

kibana_search

Search a time window. Returns timestamp + message per hit, or whole documents.

kibana_histogram

Hits per time bucket, to see when an error started.

http: any cookie-authenticated site or API

"admin": {"type": "http", "base_url": "https://admin.acme.internal", "probe": "/api/me",
          "csrf": {"cookie": "XSRF-TOKEN", "header": "X-XSRF-TOKEN"}}

Tool

What it does

http_get

GET a path on the site. Returns status, content type, and the JSON or text body.

http_request ✎

POST / PUT / PATCH / DELETE with a JSON or form body. Sends the CSRF header from the named cookie.

Custom connectors

For an internal tool that needs more than http_get, write a connector in your own private module and list it under plugins. A complete example is in examples/custom_connectors/acme_connectors/feature_flags.py:

from chrome_session_mcp.registry import Connector, S, connector_type, tool
from chrome_session_mcp.util import dumps

@connector_type("acme-flags")
class FeatureFlags(Connector):
    probe_path = "/api/me"         # a GET that succeeds only when logged in
    login_path = "/login"          # where to send the user on expiry
    options = ("environment",)     # extra config keys this type accepts

@tool("flags_get", "Read a feature flag", "Read one feature flag.",
      {"key": S("Flag key.")}, required=["key"], type="acme-flags")
def flags_get(f, key):
    return dumps(f.get_json(f"/api/flags/{key}"))
{
  "plugin_paths": ["~/acme-connectors"],
  "plugins": ["acme_connectors.feature_flags"],
  "connectors": {"flags": {"type": "acme-flags", "base_url": "https://flags.acme.internal"}}
}

What the base class does for you:

  • f.call() and f.get_json() send the cookies, recognize a logged-out answer, run login recovery, and turn HTTP errors into a ToolError message for the agent.

  • f.url() refuses any absolute URL on another host, so the connector's cookies cannot be sent to a different site.

  • Tools registered with write=True are hidden unless the instance has allow_write.

  • Override is_expired(resp) to recognize your app's own "please log in" answer, and request() to add headers (for example a CSRF token or an SSO header read from a cookie).

Keep connectors that describe internal systems (hostnames, API paths, IDs) in a private repository. Only the generic server needs to be public.

Security model

Read SECURITY.md before you use this with production systems. In short:

  • The server acts as you, with your browser session. Give it only to agents and prompts you would trust at your own keyboard.

  • Cookies are read from your local Chrome profile on demand. The server copies the (still encrypted) cookie database to a private temp file, reads it, and deletes it at once; decrypted cookie values stay in memory only. The Slack xoxc token is the exception: it is cached in a 0600 file under the cache directory.

  • Each connector sends cookies only to its own host.

  • Write tools do not exist for the agent until you opt in per instance.

  • Large outputs and Confluence backups are written to ~/.cache/chrome-session-mcp/ with 0600 permissions. They can contain whatever the tool read: clean the folder as you would clean browser downloads.

Troubleshooting

Symptom

Fix

no Chrome cookies for <host>

Open the site in Chrome and log in once. If you use several Chrome profiles, set chrome_profile.

Keychain prompt on every start

Choose Always Allow on the Chrome Safe Storage prompt.

still not logged in after 180s

Finish the login in the Chrome window that opened (same profile), wait about 30 s for Chrome to save cookies, then retry.

Login succeeds but calls are still rejected

You logged in with another account, or in another profile than the one the cookies are read from. auth_status shows the profile.

CERTIFICATE_VERIFY_FAILED

Install certifi (pipx inject chrome-session-mcp certifi), or add your corporate CA to the system store.

Linux: cookies decrypt to garbage

Install secret-tool (libsecret-tools), or set CHROME_SAFE_STORAGE_PASSWORD.

Development

python3 -m unittest discover -s tests -v      # no network, no Chrome needed
PYTHONPATH=src python3 -m chrome_session_mcp   # run the server from the checkout

The MCP stdio transport is newline-delimited JSON-RPC 2.0. The server implements initialize, tools/list, tools/call, and ping directly, and runs each tool call on a worker thread, so a tool that is waiting for a login does not block ping.

Pull requests are welcome, in particular new connector types. A new type needs a module under src/chrome_session_mcp/connectors/, a section in this README, and unit tests that do not touch the network.

License

MIT

Available Tools

4 tools
auth_statusCheck loginsA
Read-only

Check which connectors currently have a working Chrome session, without opening a browser.

Inputs: instances.

list_connectorsList configured connectorsA
Read-only

List the connectors in the config file (name, type, base URL, whether writes are enabled), plus any config errors. Call this first to learn which instance names to pass to other tools.

Inputs: no named parameters.

loginLog in through ChromeA
Read-only

Open Chrome on a connector's login page and wait until its session works. Other tools already do this by themselves when they hit an expired session; use this to log in ahead of time.

Inputs: instance (required), wait_seconds.

open_in_browserOpen a page in ChromeA

Open a URL in the user's own Google Chrome so they can look at it themselves (a dashboard, a failing build, a page you just edited). It opens in the Chrome profile that holds that site's cookies, so the page is already logged in. Only http/https URLs.

Inputs: url (required), profile.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool targets a distinct concern: config inspection (list_connectors), passive session checking (auth_status), active login (login), and opening a URL for the user (open_in_browser). The only mild overlap is auth_status vs login, but descriptions clearly separate passive checking from performing a login.

    Naming Consistency3/5

    Names use three different patterns: verb_noun (list_connectors, open_in_browser), noun_phrase (auth_status), and a bare verb (login). Still readable and each name hints at its purpose, but the convention is mixed.

    Tool Count5/5

    Four tools are tightly scoped to the server's apparent purpose of managing authenticated Chrome sessions. Each tool has a clear, non-redundant role with no filler.

    Completeness4/5

    The session lifecycle (discover connectors, check status, log in, use the session to open pages) is covered. Minor gaps exist, such as no logout/clear-session or a tool to programmatically read page content from a connector, but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to control the user's Chrome or Firefox browser, leveraging existing sessions for tasks requiring authentication and user handoff.
      18
      47 npm
      21
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Enables AI agents to drive your real, logged-in Chrome browser with existing sessions and cookies, bypassing CAPTCHA and anti-bot measures, with support for multi-session and human-in-the-loop workflows.
      40
      64
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to access authenticated websites by reusing your existing browser profile and cookies, so you never share passwords and sessions persist between runs.
      5
      5
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to drive the user's real, already-logged-in Chrome browser locally, so they can read and navigate pages, click, type, fill forms, take screenshots, and inspect cookies, tabs, console, and network traffic without headless browsers or remote-debugging ports.
      1 npm
      ISC