taxme-mcp
An MCP server that drives the Canton of Bern TaxMe/BE-Login portal with a real browser — log in once via SwissID/AGOV, then read your tax data and navigate/fill a return draft, with final submission gated behind an explicit confirmation.
Session management —
taxme_statuschecks whether the cached session is alive;taxme_loginopens a visible Chromium window for the interactive SwissID/AGOV login (incl. 2FA) and caches the session to disk so later calls run headless without re-login.Read your data —
taxme_account_statementreturns open CHF amounts per tax year (Kantons-/Gemeindesteuern, direkte Bundessteuer, Gemeindeabgaben);taxme_list_returnslists returns with status (In Bearbeitung / Quittiert). Both returnunparsablerather than a misleading empty list when the page isn't what it should be.Navigate a return —
taxme_open_return {year}opens a return (handling the popup tab, verifying the year),taxme_menushows left-menu sections,taxme_goto_section {name}clicks one and returns its fields, andtaxme_snapshotgives breadcrumb/url plus an optional PNG screenshot.Inspect and edit fields —
taxme_get_fieldslists interactive fields (id, type, value, label, context, radio group,locked), cut at alimit;taxme_fillsets text/radio/checkbox/dropdown by field id or label substring and reads every value back, reportingok:falseor awarningwhen the portal didn't really take it.Click and read results —
taxme_clickpresses a button/link by visible text (or exact row button id), andtaxme_resultsreads the Ergebnisse / Steuerberechnung of the open return.Gated submission —
taxme_submit_returnwithoutconfirm:trueonly opens the Abschluss page and returns a dry run namingwould_click; nothing is filed. It refuses when there's no submit button, the return is already filed, the page is unreadable, or no return is open.Limits — Canton of Bern only, no API (Playwright + text/URL selectors, so portal updates can break it), drafts only by design, and the schema exposes no upload/download tools (README documents
taxme_upload/taxme_download, which are absent here).
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., "@taxme-mcp list my tax returns"
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.
taxme-mcp
Read and fill your Canton of Bern tax return (TaxMe / BE-Login). Drafts only — submission is gated.
Unofficial, and inherently fragile. This drives a web portal with a real browser because the service offers no retrieval API. Portal updates break selectors without warning, and a broken selector means a failed run rather than a wrong result. It is published because it is useful, not because it is guaranteed — pin a version, read the errors, and expect to update. Use it for your own account and respect the provider's terms of service.
An MCP server for the Canton of Bern tax portal TaxMe / BE-Login (belogin.directories.be.ch). From any MCP client (Claude Code, Claude Desktop, …) you can read your account statement and your tax returns, and navigate and fill a return — open it, walk the menu sections, read the fields on a page, set values, click buttons and read the tax calculation.
What it is (and the SwissID / AGOV constraint)
BE-Login has no public API and authenticates through SwissID / AGOV (the Swiss government login, incl. 2FA). There is no headless way in: the login is an interactive browser flow you have to complete yourself. So this server drives the real portal with Playwright browser automation. Two consequences:
You log in once, in a visible browser window (
taxme_login). Everything after that runs headless against the session you established.It is inherently fragile. Portal releases can change page structure and break selectors; the server uses text/URL-based selectors with fallbacks, but expect occasional breakage after a TaxMe update.
It is full-featured: besides reading, it can open a return, walk the menu, read fields, fill them (text / radio / checkbox), click buttons (Neuen Eintrag erfassen, Speichern, Nächste Seite …) and read the results.
Safety: the server only fills drafts. The final submission (
taxme_submit_return) is gated behind an explicitconfirm: true; without it you get a dry-run of the Abschluss page and nothing is submitted.
Private use, for your own BE-Login account only. Respect the portal's terms of use.
Related MCP server: elster-mcp-server
Prerequisites
Node.js ≥ 20.19 (
node --version).Install dependencies and a Chromium build for Playwright:
git clone git@github.com:sapn95/taxme-mcp.git cd taxme-mcp npm install npx playwright install chromium # downloads a Chromium into the Playwright cachenpx playwright install chromiumis required unless a Playwright Chromium is already cached on the machine. See Troubleshooting if the browser can't be found.
Session model — log in once, stay logged in
The whole point of this server is that you don't re-login every time.
Run
taxme_loginonce. A visible Chromium window opens; complete the SwissID / AGOV login (incl. 2FA) yourself. The server waits up to ~8 minutes.The session is cached two ways so it survives server restarts:
a persistent Chromium profile in
~/.taxme-mcp/profile(keeps the trusted-device state, so AGOV doesn't re-prompt 2FA), andthe full session — including session cookies — mirrored to
~/.taxme-mcp/state.jsonvia PlaywrightstorageState()after login and after every successful call.
On startup the server re-seeds a fresh browser context from
state.json, so the AGOV session keeps working across restarts until it genuinely expires.When it does expire, any tool returns
{"status": "login_required"}— just runtaxme_loginagain.
So the normal flow is: taxme_login once, then use the read/edit tools freely;
re-login only when you actually get login_required.
flowchart TD
C["MCP client"] -->|"stdio JSON-RPC"| S["taxme-mcp"]
S --> Q{"Is the cached<br/>session still good?"}
Q -->|"yes"| DRIVE["Playwright drives<br/>the TaxMe portal"]
Q -->|"no"| LR["every tool answers<br/>login_required"]
LR --> LOGIN["taxme_login<br/>visible window, waits ~8 min"]
LOGIN --> ME["you complete SwissID / AGOV yourself —<br/>2FA, or one Touch ID on an<br/>installed, signed browser"]
DRIVE --> R[("BE-Login → TaxMe")]
ME --> R
DRIVE -.->|"after every successful call"| ST
ME -.->|"after login"| ST
subgraph disk["on disk — live cookies for your tax account"]
P["profile/<br/>keeps the device trusted,<br/>so AGOV stops re-prompting 2FA"]
ST["state.json<br/>Playwright storageState"]
end
disk -.->|"re-seeded into a fresh<br/>context on startup"| Q
classDef secret fill:#fdecea,stroke:#c0392b
classDef you fill:#fff4e5,stroke:#d9822b
class P,ST secret
class ME,LOGIN you
style disk fill:#fbfbfb,stroke:#999,stroke-dasharray: 4 3The two red boxes are the reason the section below says what it says: both hold live cookies for your tax account, and anyone holding them is you until the session expires.
Security:
state.json(and theprofile/directory) contain live session cookies for your tax account. They are secrets. Both are in.gitignore— never commit or share them. Anyone withstate.jsoncan act as you on the portal until the session expires. Delete them to force a clean logout.
Override the locations with env vars if you want:
Variable | Default | Purpose |
|
| browser profile dir (holds the session — secret); empty = a throwaway profile |
|
| cached |
| auto-detect |
|
| — | legacy alias for |
| the real portal | portal base URL; exists so the test suite can drive a local fixture instead of a real taxpayer's account |
|
| scales the fixed pauses that wait for TaxMe to rebuild the page, and nothing else — no timeout is derived from it. Only shortens: anything that is not a finite number in |
A variable that is set, even to the empty string, is authoritative: an empty
TAXME_STATE means no session cache, not "fall back to the default one".
Anything else would make "no session" impossible to express — and would let a
test that thought it was isolated quietly open the real account.
Which browser, and why it decides how you log in
BE-Login authenticates through SwissID/AGOV, and the browser is not a matter of
taste: Playwright's bundled Chromium reports
isUserVerifyingPlatformAuthenticatorAvailable() === false, so the portal never
offers a passkey and falls back to password plus SMS. An installed, signed
browser reports true and can reach the macOS platform authenticator, which
turns the same login into one Touch ID confirmation.
The server therefore prefers an installed system browser — chrome,
chrome-canary, edge, brave, in that order — and only falls back to the
bundled Chromium. Override with TAXME_BROWSER (a key from that list, chromium,
or an absolute path); TAXME_CHROMIUM still works as an alias.
For the underlying detail, including why a software passkey cannot be used at all, see the write-up in private-routines/reference/swissid-login.md.
Register a passkey once in Safari or Chrome under your SwissID account settings; after that the portal offers it ahead of the password.
Register in Claude Code
From the repo directory, register the server for your user (use an absolute
path to index.js):
claude mcp add taxme --scope user -- node /absolute/path/to/taxme-mcp/index.jsThat writes an entry into ~/.claude.json. Equivalent manual snippet:
{
"mcpServers": {
"taxme": {
"command": "node",
"args": ["/absolute/path/to/taxme-mcp/index.js"]
// optional:
// "env": { "TAXME_STATE": "/custom/path/state.json" }
}
}
}Restart Claude Code (or reconnect the MCP server), then run the taxme_login
tool once to establish the session.
Other MCP clients (Claude Desktop, etc.) take the same command / args in
their own MCP config.
Tool reference
Read / session
Tool | Args | Purpose |
| — |
|
| — | open a visible window for the SwissID/AGOV login (waits up to ~8 min); caches the session. Only |
| — | open amounts (CHF) per tax year — Kantons-/Gemeindesteuern, direkte Bundessteuer, Gemeindeabgaben. A statement prints a due date under every claim, and the 2024 assessment falls due in 2025, so an amount is only reported under a year the page itself puts it under; when none can be, you get |
| — | tax returns (Steuererklärungen) with status (In Bearbeitung / Quittiert …). An empty list is only reported when the case list itself is on the page: a page that is not one — a maintenance notice, an error page — and a list whose rows carry no year we could tie them to are both |
Navigate & edit a return
Tool | Args | Purpose |
|
| open a return for editing; returns the menu sections (handles the edit popup tab). Only |
| — | left-menu sections + status of the open return. The menu is on every page of a return and on no other page, so a page carrying none is no return: that comes back as an error naming where the browser is, not as an empty list of sections. |
|
| click a menu section by name (substring); returns its fields — cut at 60 like |
|
| interactive fields on the current page ( |
|
| breadcrumb + url of the current page; |
|
| set fields — |
|
| click a button/link by visible text (Neuen Eintrag erfassen, Speichern, Nächste Seite, Vorherige Seite, Ändern …); an exact label wins, a substring is the fallback, and |
|
| attach receipts on a Belege hinzufügen page (open it with |
|
| save a printout or receipt as PDF: clicks |
| — | read the Ergebnisse / Steuerberechnung of the open return. Reaching that section is a precondition, and it is settled the way |
Submit (gated)
Tool | Args | Purpose |
|
| ⚠️ DANGER — irreversible final submission (Abschluss → Steuererklärung einreichen). Without |
A typical edit session: taxme_login → taxme_list_returns →
taxme_open_return {year} → taxme_goto_section {name} → taxme_get_fields →
taxme_fill {values} → taxme_click {label: "Speichern"} → taxme_results.
JSF quirks handled
TaxMe is a JSF (JavaServer Faces) app with a few sharp edges the server already smooths over, so you don't have to:
Radio buttons are set by clicking the associated
<label>, falling back to a JSclick()+ a dispatchedchangeevent — plain.check()on the input doesn't reliably trigger JSF's listeners. Intaxme_filla radiovaluemay be the option value or its visible label. The button is read back afterwards: a JSF group is re-rendered by the server when it hears the change and can come back unanswered, and an answer that did not stick must not be reported as given.Switched-off widgets. A section can be Ausgeschaltet aufgrund Ihrer Eingaben, and its inputs are then
disabled. The browser never submits a disabled input, sotaxme_fillrefuses one (locked: "disabled") instead of setting it in JavaScript and reporting a value the portal will never receive.Amounts are whole francs. Enter
12000, not12000.00/12'000. The form drops the centimes silently, sotaxme_fillreads every value back and returns awarningwhen the field ended up holding something other than what it was given — a wrong number in a tax return should not look like a success.The edit popup tab: opening a return spawns a new browser tab;
taxme_open_returnwaits for and switches to that popup, and the other edit tools always target the live edit tab automatically.JSF component ids are unstable across releases, so selectors are text/URL-based with fallbacks.
Troubleshooting
{"status": "login_required"}— the session expired (or you never logged in). Runtaxme_loginand complete SwissID/AGOV in the window that opens. This is normal and expected periodically.The login window doesn't appear / login can't complete —
taxme_loginruns headed on purpose (AGOV needs interaction). It must run on a machine with a display; it won't work over a headless/SSH session with no desktop. Everything else runs headless.Chromium not found — install it with
npx playwright install chromium, or pointTAXME_CHROMIUMat an existing Chromium/Chrome-for-Testing binary. The server auto-detects the Playwright cache (~/Library/Caches/ms-playwright/chromium-*on macOS).Everything says
login_requiredeven right after logging in — yourstate.json/ profile may be stale or corrupt. Delete~/.taxme-mcp/state.json(and, if needed,~/.taxme-mcp/profile/) and runtaxme_loginagain.Selectors broke after a portal update — TaxMe changed its markup. Use
taxme_snapshot { "screenshot": true }andtaxme_get_fieldsto see the current page, and open an issue.Only Canton of Bern. Other cantons use different portals; this server is TaxMe-specific.
Releasing
Published from CI with npm Trusted Publishing (OIDC) — there is no npm token anywhere: no secret to store, rotate or leak. npm recommends this over an automation token, and is restricting tokens that bypass 2FA.
One-time setup per package, on npmjs.com -> the package -> Settings -> Trusted Publisher:
Field | Value |
Organization or user | sapn95 |
Repository | taxme-mcp |
Workflow filename | release.yml |
Allowed actions | npm publish |
The workflow filename must match exactly. That is deliberate: it stops any other workflow in the repo from publishing under your name.
Then every release is one command:
npm version patch && git push --follow-tagsThe tag triggers the release workflow: it upgrades npm (trusted publishing needs
= 11.5.1 and Node >= 22.14), refuses a tag whose version disagrees with package.json, runs the gate, and publishes with a signed provenance statement.
If the publish fails with 404
npm notice publish Signed provenance statement ... from GitHub Actions
npm error 404 Not Found - PUT https://registry.npmjs.org/taxme-mcpProvenance was signed, so OIDC worked — the registry simply does not accept this workflow as a publisher yet. That means the trusted publisher is not configured, or the repository / workflow name does not match. npm answers 404 rather than 403 so as not to reveal whether the package exists. It is not a credential problem: there is no credential, by design.
Checks
npm run gate # syntax, lint, smoke, hygiene, tests with coverage floors
npm test # the test suite alone
npm run coverage # the suite plus the enforced coverage thresholds
npm run mutate # mutation-test the lines this branch changednpm run gate is what CI runs. It needs a Chromium
(npx playwright install chromium), because the tests drive the real automation
rather than a mock of it.
How the portal is tested without a portal. test/fixture-portal.mjs is a
local HTTP server that serves the DOM the automation depends on, including the
traps that made it what it is: a radio whose <input> is invisible so only its
label can be clicked, a second radio group with no label that swallows the click
and commits only on a dispatched change, a checkbox the portal has switched off
that can still be ticked from JavaScript but never submitted, element ids with
colons in them, an amount field that drops the centimes, a return that opens in a
second tab (and one that comes back as the login page, as a maintenance page, or
as a different tax year), menu entries and buttons that are prefixes of each
other, a radio group the server re-renders and hands back unanswered, a section
the portal refuses to open so that the overview you were on comes back with a
banner, a Kontoauszug whose due dates print years that are not headings (and a
Kontoauszug link that answers with no Kontoauszug on it at all), and a
session cookie whose absence shows up as a perfectly normal-looking page saying
Angemeldet als: Benutzer. TAXME_BASE_URL points the server at it, so no test can reach the
real BE-Login. Every assertion about a click or a submission is made against
what the fixture received, not against what the server reported.
The submission gate has its own file: test/safety.test.mjs calls
taxme_submit_return without confirmation, with confirm:false, and with every
value that looks like consent but is not the boolean ("true", 1, "yes",
["true"]), and asserts each time that the fixture received nothing. The last
test in that file confirms with confirm:true and checks that a submission
does arrive — otherwise the six tests above it would prove nothing.
The smoke test completes the MCP handshake over stdio and asserts the things that have actually broken here — a server version drifting from package.json, a tool in the dispatcher but missing from the tool list (or advertised and unhandled), a required property absent from a schema, and descriptions too thin to choose a tool from. The hygiene scan refuses secrets, tracked session files and personal identifiers.
Roughly 90% of index.js is covered. The rest is mostly the callbacks handed to
Playwright's evaluate(): they execute inside Chromium, so Node's coverage never
sees them run — they are exercised, just not counted.
Mutation testing
npm run mutate asks a different question from everything above: not "do the
tests pass" but "would they notice if a guard were removed". StrykerJS deletes
one piece of behaviour at a time and reruns the suite; whatever survives is
something no assertion is watching.
It found eleven real gaps in the sibling pingen-mcp
after model review rounds had stopped turning anything up. Here it runs over
the lines a branch changed rather than the whole file, because this suite
drives a real browser once per mutant and a full pass costs hours.
npm run mutate:all does the whole file if you have the time;
stryker.config.json explains every setting that is not a default, including
why incremental mode is off.
License
MIT © sapn95
Available Tools
13 toolstaxme_account_statementA
Open tax amounts (CHF) per tax year. Amounts are only reported under a year the statement itself puts them under; if none can be, the answer is status "unparsable" rather than an empty list that would read as nothing owed. A page that is not a Kontoauszug at all — a maintenance notice, an error page — is "unparsable" too: an empty list is only reported when the statement itself is on the page.
Inputs: no named parameters.
taxme_clickA
Click a button/link by visible text (e.g. "Neuen Eintrag erfassen", "Speichern", "Nächste Seite", "Vorherige Seite", "Ändern"). An exact label wins; failing that a substring matches, and the reply names the button that was actually pressed. An empty or blank label is refused rather than resolved — an empty substring matches every element on the page, so it would press whichever button comes first.
Inputs: label (required).
taxme_fillA
Set fields on the current page. Each value: {target, value}. target = field id OR a label/context substring. value must be text, a number or true/false — text→typed (use whole francs for amounts), radio→option value or label, checkbox→true/false (ja/nein, 1/0 and on/off are understood too). A value that is neither a yes nor a no, an option neither a radio group nor a dropdown has (the reply lists the ones it does), and a field the portal has switched off are all refused rather than guessed at, and every value is read back afterwards and compared with what was asked for — a radio the portal hands back unanswered, and a dropdown it hands back on another option or on none, come back as ok:false, not as set.
Inputs: values (required).
taxme_get_fieldsA
List interactive fields on the current page (id, type, value, label, context, name for a radio — the group, i.e. the one question, its button belongs to — and locked when the portal has switched the field off; a locked field takes no value). Long forms are cut at limit (default 60) and the reply says how many were left out; taxme_fill still resolves against every field.
Inputs: limit.
taxme_goto_sectionA
Click a menu section by name (substring) in the open return; returns the fields on that page, cut at 60 like taxme_get_fields and saying so with truncated/total. Landing there is checked: TaxMe refuses to open a section while the form still has errors, and the page it hands back instead comes back as an error naming the section you are really on — not as that section's fields under the name you asked for. Which section that is is decided by the menu entry the breadcrumb names, not by the name appearing somewhere in it, because these names nest both ways round ("Wertschriften" at the front of "Wertschriftenverzeichnis", "Einkünfte" at the end of "Übrige Einkünfte"). A breadcrumb is a path and the page is the end of it, so it is read as a path: the last of its steps that names an entry of this menu, and within that step the longest entry, since a longer name that fits contains every shorter one nested inside it. A page carrying no menu is no return at all — an expired session lands on the login form — and comes back as an error saying so.
Inputs: name (required).
taxme_list_returnsB
Tax returns with status. An empty list is only reported when the case list itself is on the page: a page that is not one — a maintenance notice, an error page — and a list whose rows could not be read are both status "unparsable", because "there is nothing to file" must not be concluded from a page that was never asked the question.
Inputs: no named parameters.
taxme_loginA
Open a visible window for the SwissID/AGOV login (waits up to 8 min). Only status "ok" means the login went through: the portal is asked afterwards whether anybody is logged in, because the login page is served on the portal's own address and being there proves nothing. A login that was never completed comes back as login_required, and nothing is cached.
Inputs: no named parameters.
taxme_open_returnA
Open a tax return (year) for editing; returns the menu sections. Handles the edit popup tab. Only status "ok" means the return is open: the page is checked against the year that was asked for, so a login page or another case comes back as login_required / not_open / wrong_year instead.
Inputs: year (required).
taxme_resultsA
Read the Ergebnisse / Steuerberechnung of the open return. Reaching that section is a precondition, and it is settled the way taxme_goto_section settles it — by the menu entry the breadcrumb names — before a word of the page is read: a portal that refused to open the section comes back as an error naming the page you are really on instead of that page's text. A breadcrumb that names no entry of this menu settles nothing there, though, and where it has settled nothing the page itself has to say the section is open before an amount is read off it: the calculation is only ever read from a line the word HEADS — never from the left-menu entry, which is on every page of the return — and, absent a breadcrumb naming the entry, only when that line IS a heading of the page (a heading tag, a legend, a caption, a title/header panel) rather than a sentence beginning with the same word, since a refusal banner can be written either way round and word order is the portal's phrasing, not evidence about which page is open. A click that landed on a page with no menu at all — an expired session lands on the login form — is reported as no return being open, not as a page carrying no calculation.
Inputs: no named parameters.
taxme_snapshotA
Current page breadcrumb/url; set screenshot:true for a PNG path.
Inputs: screenshot.
taxme_statusA
Check whether the BE-Login/TaxMe session is alive (ok) or an interactive SwissID/AGOV login is needed (login_required). Call this before anything else; it also refreshes the cached session.
Inputs: no named parameters.
taxme_submit_returnA
DANGER: final submission (Abschluss → Steuererklärung einreichen). Irreversible. Requires confirm:true; otherwise returns a dry-run of the Abschluss page, naming in would_click the one button a confirmed call would press. Reaching that page is a precondition: if no submit button is there, the call is refused rather than pressing whatever the current page happens to offer. A page that already reports the return as filed (already_submitted) is refused too, confirm:true and all — a confirmation that was on the page beforehand could not prove anything about a second click. A page whose text could not be read at all (page_unreadable) is refused for the same reason one step further back: a read that failed is not a page that said no. In both cases the submit button is named as not_clicked rather than would_click, because nothing would be pressed. And a page carrying no menu at all is no return — an expired session lands on the login form — which is said in those words rather than as the Abschluss page merely not being open.
Inputs: confirm.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct action or resource: status/login handle session, account_statement/list_returns/open_return manage tax data, menu/goto_section/get_fields/snapshot navigate and inspect, fill/click modify, results reads calculations, submit_return finalizes. No two tools have overlapping purposes; descriptions reinforce the boundaries.
All names share the taxme_ prefix and use snake_case, but the pattern mixes verb-noun forms (list_returns, open_return, get_fields) with noun-only forms (status, menu, snapshot, results). This is mostly consistent and predictable, with minor deviations.
13 tools is well-scoped for a tax filing automation server. Each tool addresses a necessary step in the workflow—from session management to form interaction to submission—without redundancy or bloat.
The tool surface covers the full lifecycle: login, status check, listing returns, opening returns, navigating sections, reading fields, filling values, clicking buttons, viewing results, and submitting. There are no obvious dead ends or missing critical operations for the stated purpose.
Maintenance
Related MCP Connectors
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
TaxSort — Tollbooth-monetized MCP server for personal tax transaction classification
MCP server for FormBro Canadian immigration application automation.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server for interacting with Kanton Luzern tax declarations on eSteuern.LU, enabling field catalogue search and live declaration editing.MIT
- AlicenseAqualityDmaintenanceAn MCP server that allows AI assistants like Claude to automate interactions with the German tax portal ELSTER via Puppeteer, including form filling, submission, and session management.1451 npm34MIT
- AlicenseBqualityDmaintenanceMCP server exposing all major Swiss official public APIs as native tools for any MCP-compatible AI agent.3412 npmMIT
- AlicenseAqualityBmaintenanceRead-only MCP server for the Swiss eBill portal, enabling users to list bills and download invoice PDFs via an authenticated browser session. It cannot approve, release, or pay anything.83 npmMIT