chrome-session-mcp
Connects to Confluence using your existing Chrome session, allowing access to Confluence content by default and edit capabilities when write access is enabled for that connector.
Integrates with Grafana instances using your existing Chrome session cookies. Provides tools to resolve dashboard short links, inspect dashboard variables and panels, run panel queries with summary statistics, and make GET requests to Grafana HTTP API paths, with session rotation and login recovery.
Connects to Jenkins instances using your existing Chrome session, with support for configured job paths and optional SonarQube project linkage. Read-only by default, with write tools available only when explicitly enabled.
Connects to Kibana instances using your existing Chrome session cookies, enabling access to logged-in Kibana data with session expiry detection and login recovery.
Integrates with Slack workspaces using Chrome session cookies and localStorage token data. Provides tools to list channels, retrieve channel history and threads, search messages, look up users, and optionally post messages or thread replies when write access is enabled.
Connects to SonarQube instances using your existing Chrome session cookies, including session validation and login recovery for authenticated access.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@chrome-session-mcp check Grafana for firing alerts on checkout-service"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 topip installat 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": trueon 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/src2. 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_mcpClaude 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:
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.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.
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 | Google IAP, most SSO front doors |
| Google IAP answering a |
| Most APIs |
| Jenkins with an SSO realm |
| SonarQube |
The current user is | Confluence |
| 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 |
| Connector type (see below). Required. |
| Site root, e.g. |
| Page to open when the session expires. Default: a type-specific page on |
| Path of a |
| Read cookies for this host instead of |
| Extra static headers sent with every request. |
|
|
| Free text, shown by |
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 |
| Config file path. |
| Cache directory (default |
| Seconds to wait for a login. |
| Never open Chrome. |
| Pin the Chrome profile / user-data directory. |
| Linux: the keyring password, if |
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 |
| The configured instances and any config errors. Call it first. Without a config file it returns setup help. |
| Which instances have a working session right now. Never opens a browser. |
| Open Chrome on an instance's login page and wait until the session works. |
| 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 |
| Follow a |
| A dashboard's variables and panels. The full JSON is written to a file. |
| Run a panel's queries and return last / min / max / avg per series. |
|
|
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 |
| List channels (cached for 24 h), filtered by a regex. |
| A channel's messages in a time window. |
| A thread, from a message link or |
| Slack search syntax, e.g. |
| A user's profile by ID or email. |
| 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 |
| Every pipeline stage with status and duration, the log tail of each failed step, and the Sonar quality gate. |
| A build's console output: the last N lines, or |
| 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 |
| Write a page's body to a file. Return title, version, size, and counts of images / macros / comment anchors. |
| A page's attachments. |
| Replace the body from a file. Refuses the update when the page changed since you read it ( |
| Create a page. |
| Upload a file, e.g. a rendered diagram, to embed it. |
| 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 |
| Follow a |
| List index patterns. |
| Search a time window. Returns timestamp + message per hit, or whole documents. |
| 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 |
|
|
|
|
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()andf.get_json()send the cookies, recognize a logged-out answer, run login recovery, and turn HTTP errors into aToolErrormessage 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=Trueare hidden unless the instance hasallow_write.Override
is_expired(resp)to recognize your app's own "please log in" answer, andrequest()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
xoxctoken is the exception: it is cached in a0600file 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/with0600permissions. They can contain whatever the tool read: clean the folder as you would clean browser downloads.
Troubleshooting
Symptom | Fix |
| Open the site in Chrome and log in once. If you use several Chrome profiles, set |
Keychain prompt on every start | Choose Always Allow on the Chrome Safe Storage prompt. |
| 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. |
| Install |
Linux: cookies decrypt to garbage | Install |
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 checkoutThe 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
Available Tools
4 toolsauth_statusCheck loginsARead-only
Check which connectors currently have a working Chrome session, without opening a browser.
Inputs: instances.
list_connectorsList configured connectorsARead-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 ChromeARead-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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Let your AI agent operate any website through a real, logged-in browser session.
Let AI agents work in your own signed-in Chrome, with approvals and verified results.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to control the user's Chrome or Firefox browser, leveraging existing sessions for tasks requiring authentication and user handoff.1847 npm21MIT
- AlicenseAqualityAmaintenanceEnables 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.4064MIT
- AlicenseAqualityCmaintenanceEnables AI agents to access authenticated websites by reusing your existing browser profile and cookies, so you never share passwords and sessions persist between runs.55MIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmISC