ssomcp
It is an offline-first MCP server for preparing Thailand SSO Social Security contribution filings, with live portal actions gated behind a verified adapter.
Manage cached employers:
get_active_employerandchange_active_employer.Prepare contribution files offline:
prepare_contributioncalculates contributions and writes TXT/XLSX outputs for a given period, with optional baseline data.Query local filing history:
query_historyreturns totals-only audit records.Live e-Service tools are currently fail-closed:
refresh_employers,upload_contribution,verify_summary, andsubmit_contributionare unavailable until a verified live portal adapter is implemented; submission also requires explicit confirmation.Guided prompts are available:
/ssomcp,/ssomcp-change, and/ssomcp-refresh.Credentials are stored in Windows Credential Manager, and live browser login via Playwright is opt-in through
SSOMCP_LIVE=1.
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., "@ssomcp prepare the March 2025 contribution file"
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.
ssomcp
An offline-first MCP server for preparing Thailand SSO monthly contribution filings (สปส.1-10). It exposes MCP prompts and tools over stdio, backed by private local employer, history, and encrypted employee-baseline stores. A real Playwright adapter now logs in to SSO e-Service and lands inside the authenticated web app; the deeper attach/save/submit write flow is registered but stays fail-closed until its selectors are verified against a test-employer session.
Implemented
MCP TypeScript SDK v2 stdio server with legacy protocol fallback
/ssomcp,/ssomcp-change, and/ssomcp-refreshpromptsOffline
get_active_employer,change_active_employer,prepare_contribution, andquery_historytoolsReal Playwright login to SSO e-Service (
check_portal_login) with verified login-form selectors, one login attempt, and a fail-closed stop on any captcha/OTP/errorcheck_previous_submission— read the filed-contributions history (รายการประวัติการส่งเงินสมทบ) for an employer/year; verified selectors and duplicate-period lookupcreate_employer— register a นายจ้าง and capture its SSO login in one native popupWindows Credential Manager reader/writer so passwords never enter model context
Fail-closed attach/save/submit placeholders that never touch the portal until verified
Contribution calculation selected by Gregorian filing period
Floor/ceiling clamping and satang rounding
Tier-1 consistency and duplicate-ID validation
Data-driven 135-byte fixed-width TIS-620/Windows-874 TXT records
Buddhist Era conversion only at the TXT formatting boundary
Employer/employee delta comparison
Human-review XLSX generated from the same immutable calculation result as TXT
Unit tests for calculation, validation, encoding, widths, diffs, and XLSX/TXT total parity
Portal adapter contract with a deliberately disabled default implementation
One-attempt filing coordinator with duplicate-period guard
Fail-closed reconciliation against all five portal summary totals
Hard save-versus-submit boundary with per-run explicit confirmation
Atomic local employer registry with credential-field rejection
Totals-only JSONL filing history with no employee rows
Submitted-only baseline store encrypted with Windows DPAPI
Configurable baseline retention and previous-period lookup
Related MCP server: itr-mcp
Run
npm install
npm run check
npm startNode.js 20 or newer is required. After npm run build, configure an MCP host to run the
compiled stdio entry. For example:
{
"mcpServers": {
"ssomcp": {
"command": "node",
"args": ["C:\\path\\to\\sso-mcp\\dist\\src\\index.js"]
}
}
}For an offline sample without an MCP host:
npm run prepare:sampleThe sample command writes out/sso110-sample.txt and
out/sso110-review-sample.xlsx.
Storage workflow
Runtime state lives outside the repository under ~/.ssomcp/:
employers.jsonmaps nicknames to employer account and branch records.baseline/*.json.dpapicontains submitted-only employee baselines encrypted with Windows DPAPI.prepare_contributionloads the latest baseline before the requested period unlesspreviousEmployeesis supplied explicitly.history.jsonlcontains totals and statuses only;query_historynever returns employee rows.output/<account>-<branch>/<YYYY-MM>/receives atomically written TXT and review XLSX files.
The employer refresh tool will populate employers.json once the portal adapter is implemented.
Until then, tests or trusted local setup code can populate it through EmployerStore; credentials
must never be placed in that file.
Live portal use
Live browser access is off by default — a normal install opens no browser and reads no credential. Enable it with environment variables:
SSOMCP_LIVE=1— allow the real Playwright login/session (check_portal_login).SSOMCP_ENABLE_WRITE_FLOW=1— additionally allow the attach/save/submit flow. This stays non-functional until thecontributionselectors insrc/sso/portal-selectors.tsare confirmed from an authenticated test-employer session; until then it fails closed.SSOMCP_HEADFUL=1— show the browser window (default headless).SSOMCP_CRED_PREFIX— Windows Credential Manager target prefix (defaultssomcp).
Live use also requires the Playwright browser binary:
npx playwright install chromiumEach SSO e-Service นายจ้าง has its own login (unlike FlowAccount, where one login reaches
many companies — so there is no company-picker after login here). Credentials live only in
Windows Credential Manager, one Generic Credential per employer account, keyed
ssomcp:<accountNo> (e.g. ssomcp:1234567890). The login is issued per เลขที่บัญชีนายจ้าง and
covers all of that employer's branches, so branches share one credential. Managing N client
employers means N separate logins, one per accountNo.
The easiest way to populate one is create_employer: it registers the นายจ้าง and, in the same
step, opens a native OS popup to capture that employer's SSO login and writes it to Credential
Manager (CredWrite) under the right target automatically. Pass captureCredential: false to add
the profile without a login for now. The password is entered in the OS dialog and written by a
child process — it never enters chat or model context.
The username is the SSO e-Service login; the password is read by a child process and typed into the browser — it never enters chat or model context. There is exactly one login attempt per run; any captcha, OTP, or unexpected screen stops and hands off to a human, never a retry loop (a wrong-password retry on the government portal can lock the employer's account).
Important confirmation gates
The 2026+ contribution wage floor, official rounding rule, field padding, prefix-code list,
and exact government sample-file behavior remain marked as confirmation items in PROJECT.md.
The generator emits a warning when a provisional ceiling rule is used. Do not use its output
for a live filing until those items have been checked against an official or accepted sample.
The Playwright login adapter and the read-only duplicate-check (previous-submission history) are
implemented with selectors verified against the live authenticated pages. The contribution
write flow — the ส่งเงินสมทบ menu path, file attach, save, and pre-submit summary — remains
gated (SSOMCP_ENABLE_WRITE_FLOW) until those selectors are captured from the upload screens, so
upload_contribution, verify_summary, and submit_contribution still fail closed.
Available Tools
8 toolschange_active_employerChange active employerA
Select a locally cached employer by nickname or accountNo:branch. Never authenticates.
Inputs: employer (required).
get_active_employerGet active employerARead-only
Return the active cached employer and available cached employers. Never authenticates.
Inputs: no named parameters.
prepare_contributionPrepare contribution filesAIdempotent
Load the cached employer and encrypted prior baseline, calculate contributions, and atomically write review XLSX and upload TXT files. No network access.
Inputs: period (required), payDate (required), employees (required), employer, +1 more.
query_historyQuery filing historyARead-only
Read the local totals-only audit history. This is not proof of current e-Service state.
Inputs: period, employer.
refresh_employersRefresh employers from e-ServiceC
Unavailable until the verified live portal adapter is implemented.
Inputs: no named parameters.
submit_contributionSubmit contributionCDestructive
Final submission requires explicit per-run confirmation and a verified live portal adapter.
Inputs: period (required), employer (required), explicitConfirmation (required).
upload_contributionUpload and save contributionD
Unavailable until the verified live portal adapter is implemented.
Inputs: period (required), txtPath (required), employer (required).
verify_summaryVerify e-Service summaryDRead-only
Unavailable until the verified live portal adapter is implemented.
Inputs: period (required), employer (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Tools are mostly distinct by action (query, upload, verify, submit, get, change, prepare, refresh), but upload_contribution, verify_summary, submit_contribution, and refresh_employers are all described as unavailable/blocked, which could blur their intended roles until implemented.
Names mostly follow a verb_noun pattern (query_history, upload_contribution, get_active_employer, change_active_employer, prepare_contribution, refresh_employers). Minor inconsistency: verify_summary uses 'summary' rather than 'contribution', though it likely refers to the same workflow.
Eight tools is a reasonable count for a contribution-preparation workflow, though several are explicitly unavailable, making the effective toolset smaller and slightly padded.
The set covers local employer selection, contribution preparation, and submission intent, but lacks authenticated portal actions (real submission, verification, employer refresh) which are marked as unavailable; this makes the workflow incomplete for end-to-end use.
Related MCP Connectors
Malaysian SME accounting, e-Invoice and payroll for your AI. 95 tools; writes are approved drafts.
Read-only payroll calculations and multi-country tax comparisons for eight countries.
Simples Nacional (Fator R), progressive INSS/IRRF, FGTS & B2B NFS-e tax engine via x402 Base USDC.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI tools to normalize messy payroll spreadsheets (xlsx/xls/csv) into a standardized 10-column template for social insurance calculation, with automatic column detection, net-to-gross conversion, and cross-entity/month merging.4MIT
- AlicenseAqualityBmaintenanceLocal-first MCP server for Indian income tax computation, enabling users to compute taxes, compare regimes, plan advance tax, and parse Form 26AS without sending data to the cloud.16461 npm10MIT
- AlicenseNot gradedqualityDmaintenanceEnables local-first HR payroll computation with statutory social insurance, housing fund, and cumulative IIT calculations, adaptable to arbitrary spreadsheet headers via import adapters and company profiles. Supports safe performance formula evaluation and keeps PII on-device.MIT
- FlicenseNot gradedqualityCmaintenanceEnables labor and Social Security professionals to automate Spanish payroll and HR compliance workflows, including NOMINASOL procedures, SILTRA/FIE/FDI and CRA file processing, contribution and bonus calculations, SEPE contract and certificate queries, accident reporting deadlines, garnishment calculations under Art. 607 LEC, and sanction deadline tracking. It also lets users manage a local deadlines agenda with Slack alerts and Notion synchronization.-