Skip to content
Back to search

eo-mcp

MCP server for the Swiss EO portal (eo.zas.admin.ch): read and fill the loss-of-earnings claim (Erwerbsersatz) over an AGOV browser session, with a confirmation before anything is submitted

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sapn95--eo-mcp/badge.svg)](/listings/sapn95--eo-mcp)

HTML

<a href="/listings/sapn95--eo-mcp"><img src="/api/listings/sapn95--eo-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 267 lines
  1. <div align="center">
  2. # eo-mcp
  3. Read and fill your **EO claim** (Erwerbsersatz) on the Swiss EO portal. It edits drafts, and submitting needs an explicit confirmation.
  4. [![CI](https://img.shields.io/github/actions/workflow/status/sapn95/eo-mcp/ci.yml?branch=main&style=flat-square&logo=github&logoColor=white&label=CI)](https://github.com/sapn95/eo-mcp/actions/workflows/ci.yml)
  5. &nbsp;
  6. [![licence](https://img.shields.io/github/license/sapn95/eo-mcp?style=flat-square&color=4C5B5C)](LICENSE)
  7. </div>
  8. ---
  9. > **Unofficial.** The portal offers no public API. This server talks to the
  10. > JSON backend that the portal's own web client uses, and a portal release can
  11. > change that backend without notice. A change shows up as a failed call, and
  12. > the error carries what the portal answered. Use it for **your own** account
  13. > and respect the portal's terms of use.
  14. An [MCP](https://modelcontextprotocol.io) server for the **EO portal** of the
  15. Central Compensation Office ([eo.zas.admin.ch](https://eo.zas.admin.ch)), where
  16. people who served in the army, in civil protection or in civilian service claim
  17. their loss-of-earnings compensation.
  18. From an MCP client (Claude Code, Claude Desktop and others) you can register
  19. with the confirmation code, list your service periods, read and change the
  20. draft of a claim, look up your employer, attach documents and submit.
  21. ## How it works
  22. The portal logs you in through **AGOV**, the login of the Swiss authorities.
  23. That login is interactive and you complete it yourself, once, in a visible
  24. browser window (`eo_login`).
  25. After that the browser is only there to hold the session. Every tool call is an
  26. HTTP request to the portal's backend under `/napg/api/6`, sent with the
  27. browser's cookies. Nothing is clicked and no page is parsed, so a redesign of
  28. the portal's pages does not affect this server. A change to the backend does.
  29. > **Safety:** the server changes **drafts**. A claim reaches the compensation
  30. > office only through `eo_submit` with `confirm: true`. Without it you get a
  31. > dry run that shows the period, the form and the attachments as they would be
  32. > sent, and nothing leaves.
  33. ## What has been checked against the real portal
  34. Checked on the live portal on 20 November 2026 (web client 13.4.3, backend
  35. 14.0.3), with one civil protection period of an employee:
  36. - `eo_status`, `eo_list_periods`, `eo_get_form`, `eo_search_employers`,
  37. `eo_compensation_offices`
  38. - the refusal of `eo_update_form` and `eo_submit` on a claim that is already
  39. with the compensation office
  40. - attaching to a running browser through `EO_CDP_URL`
  41. Checked only against the fixture portal in `test/`, which answers in the shapes
  42. recorded from the real one: `eo_login`, `eo_register`, the `not_registered`
  43. status, a successful `eo_update_form`, the attachment tools and a confirmed
  44. `eo_submit`. The endpoints, the request bodies and the answers the fixture
  45. gives for these come from reading the portal's web client. Until someone
  46. has run them on a live draft, read the form back with `eo_get_form` after a
  47. change, and look at the dry run before you confirm.
  48. Only the employee case has been seen end to end. Students, the self-employed
  49. and the unemployed have their own fields in `activity.activityDetails`, and
  50. this server does not know them. `eo_update_form` passes on what you give it and
  51. the portal validates it.
  52. ## Prerequisites
  53. - **Node.js 20.19 or later**
  54. - A Chromium-based browser. An installed Chrome, Edge or Brave is preferred
  55. over Playwright's own Chromium, which cannot reach the platform
  56. authenticator, so AGOV offers no passkey there. Only the default macOS
  57. install locations are searched. Anywhere else, set `EO_BROWSER` to the
  58. absolute path of the browser, or install Playwright's Chromium.
  59. ```bash
  60. git clone https://github.com/sapn95/eo-mcp.git
  61. cd eo-mcp
  62. npm install
  63. npx playwright install chromium # only if no Chrome, Edge or Brave is found
  64. ```
  65. ## Register in Claude Code
  66. ```bash
  67. claude mcp add eo -- node /absolute/path/to/eo-mcp/index.js
  68. ```
  69. Or in an MCP client configuration:
  70. ```json
  71. {
  72. "mcpServers": {
  73. "eo": { "command": "node", "args": ["/absolute/path/to/eo-mcp/index.js"] }
  74. }
  75. }
  76. ```
  77. ## First use
  78. 1. `eo_login` opens a browser window. Log in with AGOV. The tool waits up to
  79. eight minutes and returns once the portal itself answers as logged in.
  80. 2. On a new account the status is `not_registered`. Call `eo_register` with
  81. the confirmation code from the mail or SMS «Registrierung auf dem
  82. EO-Portal».
  83. 3. `eo_list_periods` now shows your periods with their `business_id`.
  84. 4. Open the period once in the portal. The portal's web client creates the
  85. form on first opening, and this server does not create one.
  86. 5. `eo_get_form`, then `eo_update_form`, then `eo_submit` without `confirm` to
  87. see the dry run.
  88. ## Session
  89. The session lives in a browser profile under `~/.eo-mcp/profile`. A persistent
  90. profile drops session cookies when the browser closes, so after each
  91. successful call the session is also written to `~/.eo-mcp/state.json` and read
  92. back on the next start. Both are created for your user only (`0700` and
  93. `0600`), because a session cookie is as good as your login.
  94. An expired session comes back as `{"status": "login_required"}` from every
  95. tool. Call `eo_login` again. An account the portal has no claimant for yet
  96. comes back as `{"status": "not_registered"}`.
  97. ## Environment
  98. | Variable | Default | Meaning |
  99. | --- | --- | --- |
  100. | `EO_PROFILE` | `~/.eo-mcp/profile` | Browser profile. Empty: a throwaway profile. The session is still cached unless `EO_STATE` is empty too. |
  101. | `EO_STATE` | `~/.eo-mcp/state.json` | Session cache. Empty: the session is not cached. |
  102. | `EO_BROWSER` | first installed of Chrome, Chrome Canary, Edge, Brave | `chrome`, `chrome-canary`, `edge`, `brave`, `chromium` or an absolute path. |
  103. | `EO_CDP_URL` | unset | Attach to a browser that already runs with `--remote-debugging-port`, for example `http://127.0.0.1:9222`, and use its session. Nothing is cached, and the browser keeps running when the server stops. |
  104. | `EO_LANGUAGE` | `de` | `de`, `fr` or `it`. The language of the office list and of the portal's confirmation. |
  105. | `EO_BASE_URL` | `https://eo.zas.admin.ch` | For the test suite, which points it at a local fixture. |
  106. `EO_CDP_URL` is for the case where you are already logged in to the portal in
  107. your own browser. A debugging port gives every local process control of that
  108. browser, so open it only for as long as you need it.
  109. ## Tools
  110. ### Session
  111. | Tool | What it does |
  112. | --- | --- |
  113. | `eo_status` | `ok`, `login_required` or `not_registered`. |
  114. | `eo_login` | Opens the login window and waits until the portal answers as logged in. |
  115. | `eo_register` | Sends the confirmation code and returns the periods. A refused code comes back with the portal's reason, for example `USED_TOKEN`, `EXPIRED_TOKEN` or `UNKNOWN_TOKEN`. |
  116. ### Reading
  117. | Tool | What it does |
  118. | --- | --- |
  119. | `eo_list_periods` | Each period with `business_id`, case status and the period as the service organisation reported it. |
  120. | `eo_get_form` | The stored form, the attachments, and the required attachment categories that are still missing. |
  121. | `eo_search_employers` | The employer register, by `name` (with optional `zip`, `town`, `canton`) or by `uid`. |
  122. | `eo_compensation_offices` | The compensation offices, with an optional `query`. |
  123. Case status: `EDITING` is a draft you can still change. `ASSIGNED` means the
  124. claim is with the compensation office. The others are `INITIATED`,
  125. `READY_FOR_ASTREINT`, `PAPER`, `CLOSED`, `PRESCRIBED`, `ARCHIVED` and `ERROR`.
  126. ### Changing the draft
  127. | Tool | What it does |
  128. | --- | --- |
  129. | `eo_update_form` | Lays `changes` over the stored form and writes it back. |
  130. | `eo_upload_attachment` | Attaches a file of at most 5 MB under a category. |
  131. | `eo_delete_attachment` | Removes one attachment by id, from a draft only. |
  132. `eo_update_form` merges objects key by key. Any other value replaces what was
  133. there, including an array and `null`. The portal uses `null` for «not
  134. answered», so it is written as a value and the key stays.
  135. ```json
  136. {
  137. "business_id": "00000000001_00000000002_1",
  138. "changes": {
  139. "isServicePeriodValidated": true,
  140. "familySituation": { "hasChildren": false }
  141. }
  142. }
  143. ```
  144. An employee, in the shape the portal stores. Take the employer from
  145. `eo_search_employers`:
  146. ```json
  147. {
  148. "activity": {
  149. "hasIncome": true,
  150. "employerInSwitzerland": true,
  151. "activityType": "EMPLOYEE",
  152. "activityDetails": {
  153. "_type": "ActivityEmployee",
  154. "employer": {
  155. "uid": "CHE000000019",
  156. "organisationName": "Example AG",
  157. "town": "Example",
  158. "npa": 1000,
  159. "address": null,
  160. "cantonAbbreviation": "BE",
  161. "compensationOffice": { "uid": "CHE000000001", "notFound": false, "accountNumber": null },
  162. "notFound": false,
  163. "byUid": true,
  164. "farmingAllowance": false
  165. },
  166. "otherEmployer": []
  167. }
  168. }
  169. }
  170. ```
  171. What the tool guards:
  172. - Only a case in status `EDITING` is written to.
  173. - The write carries the `version` that was read. If the form changed elsewhere
  174. in between, the portal answers with a conflict and nothing is overwritten.
  175. - `version`, `servicePeriodVersion` and `categoryRequirements` belong to the
  176. portal and are refused in `changes`.
  177. - The stored form is read back and compared with what you asked for. A value
  178. the portal kept differently is listed under `differing`.
  179. ### Submitting
  180. | Tool | What it does |
  181. | --- | --- |
  182. | `eo_submit` | Without `confirm: true` a dry run. With it, the claim goes to the compensation office. This cannot be undone. |
  183. `eo_submit` refuses, with or without `confirm`, when the case is not in status
  184. `EDITING`, when the period has not been confirmed as correct, when no activity
  185. is chosen, or when a required attachment is missing. After a confirmed call it
  186. asks the portal for the case list again and reports `submitted: true` only if
  187. the case is no longer in `EDITING` there.
  188. ## Troubleshooting
  189. - `login_required` right after `eo_login`: the login was not finished in the
  190. window. Call `eo_login` again.
  191. - `not_registered`: the login worked, but the account has no claimant yet.
  192. Use `eo_register` with the confirmation code.
  193. - `Für diese Periode gibt es noch kein Formular`: open the period once in the
  194. portal.
  195. - `EO_BROWSER="…" not found`: the path or name does not exist on this machine.
  196. - The portal refuses a change: its answer is under `portal`, in the portal's
  197. own words.
  198. ## Checks
  199. ```bash
  200. npm run gate
  201. ```
  202. This runs the syntax check, ESLint, an offline protocol smoke test, the hygiene
  203. scan and the test suite with a coverage floor. The suite drives the server
  204. over stdio against the fixture portal in `test/fixture-portal.mjs`, through a
  205. real headless browser. The fixture holds invented data only.
  206. The hygiene scan fails on secrets, personal data and tracked session files. A
  207. claim form holds an IBAN, a social-security number and an address, and none of
  208. that belongs in a public repository.
  209. ## License
  210. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.