mcp-ado-browser
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., "@mcp-ado-browser list my active pull requests"
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.
mcp-ado-browser
Azure DevOps for MCP — via your browser, not a PAT.
An MCP (stdio) server that gives read-only access to Azure DevOps using only your existing browser session — no PAT, no Azure CLI, no official ADO MCP, no credential provider. The only source of authentication is the session of a real browser, driven by Playwright on an isolated, dedicated profile.
It is org-wide by default: only the organization is required, and it browses every project, repo and feed you can access.
Requests reuse whatever credential your signed-in browser session already carries.
Where Azure DevOps authenticates the web app with a bearer token rather than cookies,
the server loads the app shell once, observes the Authorization: Bearer header on
the app's own API traffic, and replays that token for every host (dev.azure.com,
feeds, pkgs, almsearch). You get JSON back — never DOM scraping for data the
REST API provides. No PAT is ever created, and no token is written to disk.
Why these choices (restricted-environment friendly)
Concern | Decision |
No Playwright browser download |
|
SQLite without a native build |
|
One package, one binary | The MCP server and the |
No hardcoded values | org/project/ids come from flags/env or discovery; api-versions live only in |
Related MCP server: Azure DevOps MCP Server
How it works
flowchart TD
A["authenticate<br/>(visible, chromeless window)"] -->|"sign in once · MFA"| P[("browser session<br/>persisted on an isolated profile")]
P -. restored .-> W["headless work session"]
W -->|"loads the app shell once"| T{{"session access token<br/>(observed, in memory only)"}}
MC["MCP client<br/>(Claude / Cursor / …)"] -->|"tools/call"| SRV["mcp-ado-browser<br/>(stdio MCP server)"]
SRV --> W
T --> ADO["dev.azure.com · feeds · pkgs · almsearch<br/>(your real session)"]
ADO -->|"JSON"| W
W --> SRV
SRV <-->|"TTL + Rev freshness"| DB[("SQLite cache")]Authentication is your browser, not a PAT.
authenticateopens a real, visible browser window on a dedicated, isolated profile (never your daily browser). You sign in normally (MFA included). The tool detects success by polling an authenticated endpoint, then snapshots the browser session to disk. No PAT is ever created.Work runs headless. Subsequent runs launch the same profile headless and restore that snapshot — no window, no re-login until the session expires. The snapshot is needed because the cookie that keeps the Azure DevOps app shell loaded is a session cookie, which Chrome drops when it exits.
Requests reuse the web app's own credential. On the tenants this was tested against, the Azure DevOps web app authenticates its API with
Authorization: Bearer(MSAL) and a cookie-only request gets401on every host — the sign-in URL even carriesprotocol=cookieless. (This is observed behaviour; we found no Microsoft announcement of such a change, so treat it as something that varies rather than a rule.) The server therefore loads the app shell once, observes the token on the app's own API calls, and replays it. One token coversdev.azure.com,feeds,pkgsandalmsearchalike.The token is held in memory only and refreshed automatically on a
401. It is deliberately never written to disk: a bearer token reachable from JS is more exposed than anhttpOnlycookie — Microsoft's own MSAL guidance states browser storage is only safe absent XSS, and that its cache encryption "reduce[s] the persistence of auth artifacts, not to provide additional security". This server does not widen that exposure.401and403are kept distinct.401means the session is dead →AUTH_REQUIRED, re-runauthenticate.403means you are signed in but lack permission on that resource (a private feed, say) → a403error saying so. Re-authenticating cannot fix a permission problem.Responses are cached in a local SQLite DB (
node:sqlite) with a configurable TTL. On a stale hit, a cheap freshness check (System.Revfor work items) avoids re-downloading unchanged data.When the session dies, tools fail fast with
AUTH_REQUIRED— just re-runauthenticateand continue.
Getting started
Prerequisites: Node ≥ 22.5 and Google Chrome (or Microsoft Edge) installed. You do not need a PAT, the Azure CLI, or any admin setup.
Setup is two steps:
Register the server in your MCP client (one config entry — see your client below).
Sign in once — just ask your assistant: “authenticate to Azure DevOps”. The built-in
authenticatetool opens a visible browser window; you log in (MFA), and the session is persisted. (No separate terminal command needed.) From then on everything runs headless until the session expires — then just ask it to authenticate again.
The command every client runs is the same:
npx -y mcp-ado-browser --org <your-org>Config is passed as CLI flags (--org, --project, …) or env vars (ADO_ORG, …);
flags win. Then ask things like “list my active pull requests”, “show work item 1234
and its linked PR”, or “what feeds and packages are in this org?”.
Tip: prefer per-user/local config (not committed) so your org name doesn't land in a shared repo. Or omit
--orgfrom a committed config and setADO_ORGin your env.
Use it from your MCP client
claude mcp add ado --scope local -- npx -y mcp-ado-browser --org <your-org>Then ask Claude to “authenticate to Azure DevOps”.
{
"mcpServers": {
"ado": {
"command": "npx",
"args": ["-y", "mcp-ado-browser", "--org", "<your-org>"]
}
}
}{
"servers": {
"ado": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-ado-browser", "--org", "<your-org>"]
}
}
}Open Copilot Chat in Agent mode and pick the ado tools. (Avoid committing your org —
use ${env:ADO_ORG} or a personal config.)
{
"mcpServers": {
"ado": {
"command": "npx",
"args": ["-y", "mcp-ado-browser", "--org", "<your-org>"]
}
}
}[mcp_servers.ado]
command = "npx"
args = ["-y", "mcp-ado-browser", "--org", "<your-org>"]After registering, trigger sign-in from the chat (“authenticate to Azure DevOps”),
which runs the authenticate tool. Prefer a terminal instead? npx -y mcp-ado-browser authenticate --org <your-org> does the same thing. Tools return a structured
AUTH_REQUIRED error when the session expires — re-authenticate and continue.
Tools (tools/list)
Tool | What it does |
| All projects you can access (org-wide). |
| All Git repos across the org (or one project). |
| WIQL (org-wide by default) or full-text (almsearch); |
| Work item with |
| The separate comments endpoint (project derived automatically). |
| A comment plus its downloaded attachments (size, sha256). |
| PRs org-wide, by repo, or by project; filter by status/author/target. |
| Metadata, branches, reviewers, linked work items (repo by id or name). |
| Threads, distinguishing system vs human. |
| Artifacts feeds → packages → versions. |
|
|
| Opens a visible browser for interactive sign-in (MFA); persists the session. Run it once, or whenever a tool returns |
Commands
The single npx mcp-ado-browser binary has a few subcommands:
Command | What it does |
| Start the MCP stdio server (default). |
| Interactive sign-in (visible browser). Same as the |
| Show the profile/cache paths, the org, and whether the session is signed in (and as who). |
| Clear the persisted session and the cache (a local sign-out). No org needed. |
Switching org with the same account needs nothing special — just change
--org; one sign-in covers every org that account can access. A different account →logoutfirst, thenauthenticateagainst the other org.
Where it stores things
Everything is local to your machine, under a single dedicated folder (mode 700, never
committed). Nothing is hosted remotely — the server is a local process spawned by your MCP
client over stdio.
What | Path (default) |
Browser session (profile) | macOS/Linux: |
Session snapshot (mode |
|
SQLite cache |
|
Package code (npx cache) | macOS/Linux: |
Reset everything (forces re-login): logout, or rm -rf ~/.mcp-ado-browser.
Configuration
Flag | Env | Default | Meaning |
|
| — | Organization (required). |
|
| — | Default project scope (optional; org-wide otherwise). |
|
|
| Isolated persistent browser profile. |
— |
|
| Session snapshot (mode |
|
|
|
|
|
|
| Global cache TTL. Per-resource: |
|
| discovery/defaults | Force an api-version for all areas. |
|
| app mode | Use a normal browser window for sign-in. |
|
| headless | Run work with a visible window. |
Development & verification
npm install
npm run build
npm run verify # all offline gates (browser stack, MCP, tools, cache, artifacts, no-hardcoding)
npm run verify:live # adds the live acceptance pass against real Azure DevOps
npm run scan:secrets # pre-push secret / sensitive-data scan
npm run demo:live # drive the real stdio server as an MCP client (env-driven)npm run verify prints a detailed report, gate by gate, assertion by assertion.
BLOCKED_ON_AUTH is transitory: the run is not done until the live pass is green; the
only tolerated terminal exclusion is EMPIRICALLY_BLOCKED (with evidence), for the
cross-host artifact download only.
Security & privacy
Authentication is only your real browser session on a dedicated, isolated profile — no PAT or token is ever created, stored, or transmitted by this tool.
The session lives in
~/.mcp-ado-browser/profile(machine-local, gitignored).Fixtures and reports are anonymized;
npm run scan:secretsblocks pushes that would leak personal/org data or secrets (also enforced in CI).
License
MIT © VMargan
Available Tools
12 toolsauthenticateA
Sign in to Azure DevOps by opening a VISIBLE browser window for interactive login (MFA included). Run this once (or whenever a tool returns AUTH_REQUIRED). The session is persisted on an isolated profile and reused headless afterward — no PAT or token is ever stored.
Inputs: timeoutSeconds.
download_artifactA
Download a package artifact (.nupkg / .tgz) from a feed via the browser session (pkgs.dev.azure.com). Validates archive integrity (size, sha256, valid zip/tgz) for re-hosting.
Inputs: feedId (required), saveDir (required), version (required), protocol (required), +2 more.
get_comment_detailsA
Resolve a work item (and optionally a specific comment) AND download all related attachments (work-item AttachedFile relations + attachments referenced in the comment body). Returns metadata + downloaded content stats (size, sha256).
Inputs: workItemId (required), saveDir, commentId.
get_pull_requestA
Get a pull request with metadata, branches, reviewers and linked work items. Resolved org-wide — repoId may be a GUID or a repository name.
Inputs: prId (required), repoId (required).
get_pull_request_commentsA
Get PR threads (system vs human). Resolved org-wide — repoId may be a GUID or a repository name.
Inputs: prId (required), repoId (required).
get_work_itemA
Get a single work item with $expand=all, including relations (hierarchy, Related, and ArtifactLink PR references resolved).
Inputs: id (required), bypassCache.
get_work_item_commentsA
Get the full discussion for a work item (GET _apis/wit/workItems/{id}/comments — a SEPARATE endpoint, not part of $expand).
Inputs: id (required).
list_projectsA
List ALL Azure DevOps projects the user can access in the organization (GET _apis/projects). Use this to discover projects to browse.
Inputs: no named parameters.
list_repositoriesA
List ALL Git repositories the user can access across the organization (GET _apis/git/repositories), or within one project. Returns id, name and owning project for each repo.
Inputs: project.
search_feedsA
Browse Azure Artifacts feeds (GET feeds.dev.azure.com/_apis/packaging/feeds). Pass feedId to also list packages + versions. Each feed reports its project (null for org-scoped feeds); project-scoped feeds are addressed under their project automatically.
Inputs: feedId.
search_pull_requestsA
Search pull requests ORG-WIDE by default, or within a repo (repoId) or a project. Filters: status, creatorId, targetRef. (GET _apis/git/pullrequests)
Inputs: top, repoId, status, project, +2 more.
search_work_itemsA
Search/browse work items ORG-WIDE (cross-project) by default. Backend is WIQL (POST _apis/wit/wiql); pass text for full-text Search (almsearch), or project to scope to one project. Returns id + summary fields.
Inputs: top, text, wiql, project.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource/action: projects, repositories, work items, PRs, feeds, artifacts, and authentication. The only possible overlap is between get_work_item_comments and get_comment_details, but their descriptions clearly separate discussion retrieval from comment resolution plus attachment download.
Most tools follow a consistent verb_noun pattern (list_projects, search_work_items, get_pull_request). Minor deviations include get_comment_details (which omits 'work_item') and authenticate (verb-only), but these do not significantly hinder readability.
With 12 tools, the set is well-scoped for a browser-oriented Azure DevOps server. Each tool covers a meaningful browsing operation, and there is no redundancy or bloat.
The toolset provides good read-only coverage: listing and searching projects, repos, work items, PRs, and feeds, plus getting details and comments. Minor gaps include no explicit get_project or get_repository (though list tools return sufficient info) and no code search, but core browsing needs are met.
Maintenance
Related MCP Connectors
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Read project context and manage tasks in MCPBinder, with access you control.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Azure DevOps services including work items, repositories, pipelines, wikis, and test plans through a local MCP server that provides direct access to Azure DevOps REST APIs from your code editor.MIT
- AlicenseBqualityDmaintenanceA read-only MCP server connecting AI assistants to Azure DevOps Server (on-premises) for browsing projects, repos, builds, work items, releases, pipelines, and test results.391MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Azure DevOps projects, including work items, test results, Git repositories, and dependency analysis via the Model Context Protocol.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to interact with Azure DevOps resources such as projects, builds, repositories, work items, test plans, and wikis through natural language using the Model Context Protocol.128,342 npmMIT