termdat-mcp
This server provides read-only MCP tools for querying TERMDAT, the Swiss Federal Administration's official terminology database, to retrieve validated administrative designations in German, French, Italian, and English.
search_terms: Search TERMDAT for official names of authorities, departments, and legal acts using Lucene syntax, with filters by collection/classification, language, and field flags.
translate_term: Get the official equivalent of an administrative term in another national language (e.g., DE→FR), including preferred and alternative designations.
check_terms: Communication QA — verify up to 25 terms against validated designations, reporting each as validated, found_unvalidated, or not_found.
get_entries: Fetch known TERMDAT entries by numeric ID with full language variants.
list_collections: List the ~140 terminology collections for use as filter values.
list_classifications: List the 23 subject classifications (e.g., BILD = education) for use as filter values.
api_status: Check availability of the TERMDAT API; never returns silently empty.
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., "@termdat-mcp What is the French term for 'Bundesamt für Gesundheit'?"
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.
🇨🇭 Part of the Swiss Public Data MCP Portfolio — open-source MCP servers connecting AI agents to Swiss public and open data. This is a private project. It is independent of any employer or institutional affiliation.
🏷️ termdat-mcp
Official, validated Swiss administrative designations across DE / FR / IT / EN — with source references and validation status.
Overview
MCP server for TERMDAT, the terminology database of the Swiss Federal Administration, maintained by the Federal Chancellery. It gives an AI agent the officially validated designations of Swiss authorities, departments and legal acts across DE / FR / IT / EN — with source references and validation status.
Discovered through i14y-mcp, which catalogues TERMDAT as data service ff0c37eb-2f7c-4ff6-996e-d22b77bf52fc.
What this is — and what it is not. TERMDAT is not a subject dictionary. It is a certified name-plate archive: it will not tell you what «Sonderpädagogik» means, but it will tell you the official name of the authority responsible for it, and what that authority is called in French.
Measured coverage (live, 2026-07-19, German search over the Terminus field):
Search term | Hits |
Departement | 20 |
Bildung | 13 |
Verordnung | 8 |
Schule | 5 |
Behörde | 4 |
Sonderpädagogik | 3 |
Volksschule · Lehrperson · Schulleitung · Unterricht · Kindergarten | 0 |
The thirteen «Bildung» hits are organisational names — Bildungsdirektion, Erziehungsdepartement, Departement für Volkswirtschaft und Bildung — not pedagogical concepts. Plan accordingly: this server is strong for authority naming, official titles and abbreviations, and largely silent on domain vocabulary.
Related MCP server: swiss-ip-mcp
Features
Seven read-only tools over the official TERMDAT public v2 API.
Official designations across DE / FR / IT / EN, with source reference and validation status on every response.
Communication QA: check up to 25 terms in one call against validated designations.
Vocabulary cache (24 h TTL) for the 140 collections and 23 classifications, with stale-serve fallback.
Retry with exponential backoff (2/4/8 s); explicit
MaxEntryCountto avoid silent truncation.Dual transport:
stdio(local) and Streamable HTTP (cloud). Both serve MCP protocol revision2026-07-28.No authentication required — public, unauthenticated API (No-Auth-First).
🎯 Anchor demo query
«What are the official French and Italian names of the education directorates of the German-speaking cantons?»
Resolved with list_classifications → search_terms → translate_term.
Demo
Prerequisites
Python 3.10+
Network access to
api.termdat.bk.admin.ch— no API key needed
Installation
uvx termdat-mcpClaude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"termdat": {
"command": "uvx",
"args": ["termdat-mcp"]
}
}
}Quickstart
# Run locally over stdio (default transport)
uvx termdat-mcp
# From a checkout, without installing
PYTHONPATH=src python -m termdat_mcpConfiguration
All configuration is via environment variables. Defaults are safe for local use.
Variable | Default | Purpose |
|
| Transport: |
|
| Bind host (HTTP transport only). Loopback by default; set |
|
| Bind port (HTTP transport only) |
|
| HTTP only: explicit allowed browser origins (default-deny; never a wildcard in production). Comma-separated, e.g. |
|
| HTTP only: inbound |
|
| structlog level (JSON to stderr) |
|
| Vocabulary cache TTL in seconds |
Configuration is loaded once into a typed Settings object (pydantic-settings).
List variables. TERMDAT_MCP_CORS_ORIGINS and TERMDAT_MCP_ALLOWED_HOSTS
take a comma-separated list — the recommended spelling, and the one the
rest of the Swiss Public Data MCP portfolio uses:
TERMDAT_MCP_ALLOWED_HOSTS="mcp.example.ch,mcp.example.ch:443"A JSON list (["mcp.example.ch"]) stays valid. Surrounding whitespace and
empty entries are dropped in both forms, so a trailing comma is harmless. A
single value needs no brackets.
TERMDAT_MCP_ALLOWED_HOSTS matters in the cloud. The SDK leaves
DNS-rebinding protection off while no allow-list is configured. Bind to
0.0.0.0 in a container without this variable and the Host header is never
validated — the server cannot derive its own public name from the bind address,
and a guessed list would reject every real request with HTTP 421. It warns on
startup when it has to fall back to that state.
Cloud (Render / Railway):
TERMDAT_MCP_TRANSPORT=streamable-http PORT=8000 termdat-mcp # exposes /mcpAvailable Tools
Tool | Purpose |
| Search TERMDAT with field flags, collection and classification filters |
| Official equivalent of an administrative term in another national language |
| Communication QA: check up to 25 terms against validated designations |
| Fetch known entries by numeric ID |
| The ~140 terminology collections (filter values) |
| The 23 subject classifications, e.g. |
| Availability; never returns silently empty |
All tools are annotated readOnlyHint: true, destructiveHint: false.
MCP primitives. This server uses only the Tools primitive. TERMDAT answers
are live queries with no stable resource hierarchy to expose as Resources, and
there are no server-authored Prompts. The seven tools are small and closely
related, so they live in a single server.py rather than a tools/ package.
Architecture
┌─────────────────┐ stdio / HTTP ┌──────────────────────────┐
│ MCP host │ ───────────────► │ termdat-mcp │
│ (Claude, IDE) │ ◄─────────────── │ │
└─────────────────┘ │ vocabulary cache (24 h) │
│ 140 collections │
│ 23 classifications │
└────────────┬─────────────┘
│ httpx + retry (2/4/8 s)
▼
https://api.termdat.bk.admin.ch/v2
├── /Search (SearchTerm + InLanguageCode)
├── /Entry (EntryIds)
├── /Collection (140 values)
└── /Classification ( 23 values, incl. BILD)Architecture decision
This server uses Architecture A (live API only), with caching limited to the two controlled vocabularies.
Rationale (verified live on 2026-07-19):
The API publishes a complete OpenAPI 3.0.4 specification at
/swagger/v2/swagger.jsonand declares no security schemes — unauthenticated access, No-Auth-First satisfied.Server-side search works properly, including 11 field flags and filters by collection and classification. There is no reason to mirror the database locally, and no bulk dump is offered.
/Collection(140 entries) and/Classification(23 entries) change rarely and are needed to make filter arguments legible to an agent, so they are cached with a 24-hour TTL and a stale-serve fallback.
Consequences:
Every search is a live call;
provenanceislive_apiexcept for vocabulary lookups.Validation errors arrive as clean RFC 9110 payloads and are surfaced rather than swallowed.
Project Structure
termdat-mcp/
├── src/termdat_mcp/
│ ├── __init__.py
│ ├── __main__.py # entry point; dual transport (stdio / Streamable HTTP)
│ ├── client.py # httpx client, retry, vocabulary cache
│ ├── models.py # Pydantic models
│ └── server.py # MCP tool definitions
├── tests/
│ ├── test_client.py # offline, respx-mocked
│ └── test_live.py # hits the real TERMDAT API
├── README.md
├── README.de.md
├── CHANGELOG.md
├── LICENSE
└── pyproject.tomlSafety & Limits
Read-only. Every tool is annotated
readOnlyHint: true,destructiveHint: false; the server never writes to TERMDAT.No credentials handled. The API is unauthenticated; the server stores and forwards no secrets.
No silent empties.
api_statusand error paths surface failures instead of returning an empty result that looks complete.Truncation is explicit.
MaxEntryCountis always sent andtruncatedis reported (see Known Limitations).Terms of use are stated, not guessed. Every response repeats them in
source: reuse and republication require the sourcewww.termdat.chto be named, and the Federal Chancellery's Terminology Section to be informed of purpose and manner beforehand (statement of 2026-08-21).Egress allow-list. Requests can only reach
api.termdat.bk.admin.ch(HTTPS), enforced before every call by a frozenALLOWED_HOSTSset — no user input can redirect egress. Seedocs/network-egress.md.Loopback by default. The HTTP transport binds to
127.0.0.1;0.0.0.0is an explicit container opt-in that warns on stderr. It also sets default-deny CORS, exposing onlyMcp-Session-Id.Errors are masked. Upstream/internal error detail is logged to stderr (structlog JSON) and never returned to the model.
Accepted risks (ADRs): DNS pinning (ADR 0001) and stateful load balancing (ADR 0002) are deliberately deferred — low risk for a single-instance, single-host, no-auth server.
Container. A hardened, non-root
Dockerfileis provided for hosted deployments.
Known Limitations
Administrative scope only. See the coverage table above.
check_termsreturnsnot_found, never «incorrect», precisely because absence from TERMDAT is not evidence of error.MaxEntryCounthas a silent default of ~25. Omitting it looks like a complete result set. This server always sends the parameter explicitly and reportstruncated.CollectionIds/ClassificationIdshave a silent default ofVARIA. An ID-less/v2/Searchcovers one of 23 subject areas — the residual one — and reports the truncated result as a normal empty answer. This server sends the full classification set unless you narrow it explicitly. See issue #11.SearchTermis Lucene, and matching is on whole words. «Quellensteuer» does not match «Quellensteuerverordnung»; «Quellensteuer*» does.*,?and~are available — on an empty result, retry with a wildcard before concluding the term is absent.Field.*flags default to true where unsent.Terminus,Name,AbbreviationandPhraseologyare on unless explicitly disabled, so a partial flag set can only widen a search. This server sends all eleven flags explicitly, which is what makesfieldsable to narrow.Multilingual variants are opt-in. Without
OutLanguageCode, entries return German designations only.translate_termsets it for you.The public API exposes less than the website — deliberately. Not a scope setting, and not a defect: asked directly, the Federal Chancellery's Terminology Section confirmed on 2026-08-21 that the API covers only part of the TERMDAT records, that the selection follows the needs of the federal administration's translators, and that no fuller coverage is planned. Measured beforehand: for «Quellensteuer» the website lists 12 distinct entries and the API returns 7 at maximum recall (every language, all 11 fields, infix wildcard, all classifications and collections); the overlap is one entry, 447912. Fetching the missing IDs directly via
/v2/Entryreturns HTTP 200 with an empty body — they are not served at all, so no query can reach them. Consequence: absence from this server means absence from the API, not from TERMDAT, and there is nothing to work around. Verified 2026-07-30 with the entry IDs supplied by @dfch in issue #11.The I14Y catalogue record carries
license: null— the terms are elsewhere. Reuse and republication of TERMDAT content are permitted only with the sourcewww.termdat.chnamed, and the Terminology Section of the Federal Chancellery informed of purpose and manner beforehand (terminologie@bk.admin.ch; statement of 2026-08-21). Running this server is covered by the enquiry that produced that statement; your own downstream republication needs its own notice. Every response repeats the terms insource.Entry-level language coverage varies. Not every entry exists in all four languages;
translate_termomits entries without a target-language variant rather than inventing one.
Live probe findings (2026-07-19)
Endpoint | HTTP | Status | Note |
| 200 | ✅ | OpenAPI 3.0.4, 132 KB, |
| 200 | ✅ | requires |
| 200 | ✅ | requires |
| 200 | ✅ | 140 values |
| 200 | ✅ | 23 values, incl. |
| 404 | ❌ | no index; the I14Y record points here |
| 400 | ❌ | only two-letter ISO codes, case-insensitive |
Probe note: a correction worth recording. An earlier probe concluded that OutLanguageCode filters the result set, because adding it appeared to drop all hits. It does not. Two variables had been changed at once — the parameter and the search term — and the term itself («Volksschule») genuinely has zero hits. Verified afterwards across four broad terms: result counts are identical with and without OutLanguageCode; the parameter is purely additive. A regression test (test_out_language_is_additive_not_filtering) now guards this.
Rule of thumb: change one variable per probe call, or the API will confess to a crime it did not commit.
Live probe findings (2026-07-27) — search scope
Reported in issue #11: «Quellensteuer»
returned nothing while the TERMDAT website returned twelve hits. Three independent causes,
in descending order of effect. Entry counts, InLanguageCode=DE:
Query | ID-less ( | all 23 classifications | + free-text fields | + |
| 0 | 1 | 3 | 6 |
| 1 | 4 | 22 | 27 |
The first column is what this server sent before the fix. The VARIA default is the
dominant term: it hid FINANZWESEN, RECHT and twenty other subject areas behind an
answer that looked like a confident zero.
Probe note. The failure mode worth recording is not the count — it is that an
under-scoped search is indistinguishable from a genuine absence. In the reported session
the model read the empty result together with this server's own «absence usually means out
of scope» caveat and invented a plausible explanation for a term that was in the database
all along. A tool that narrows silently will be believed silently. Hence hint on empty
results, and a caveat that now tells the model to retry rather than to conclude.
Project Phase
This server is in Phase 1 (read-only). All tools are annotated
readOnlyHint: true / destructiveHint: false and only ever query the public
TERMDAT v2 API — there are no write, send, or filesystem capabilities.
Phase | Scope | Status |
1 — Read-only | Search, translate and check administrative designations | ✅ current |
2 — Write-capable | (none planned) | — |
3 — Multi-agent | (none planned) | — |
A transition to a later phase would require a re-audit and human-in-the-loop controls before any write-capable tool is added.
MCP Protocol Version
This server speaks two protocol eras over the same endpoint, on both transports. The client's first request on a connection decides which one applies; a later claim from the other era is refused.
Era | Revision | Who reaches it |
|
| What today's clients speak. The server answers with the revision asked for, or with the |
Per-request envelope |
| A request carrying the |
Both revisions are pinned in
tests/test_protocol_version.py and asserted
against the installed SDK, so a Dependabot bump of mcp cannot move either one
silently.
That pin alone once hid a real gap. Until 18.09.2026 the network transport
was the SDK's SSE app, which has no branch into the modern era at all — over
HTTP, 2026-07-28 was unreachable, while the constants said otherwise and
stdio served it fine. Since the switch to Streamable HTTP on /mcp, both eras
are also measured: tests/test_streamable_http.py
sends real requests of both kinds through the assembled ASGI stack and checks
the negotiated revision, the mandatory resultType, and the -32022 rejection
of an unknown modern revision.
Note that the SDK's LATEST_PROTOCOL_VERSION is an alias for the modern
era, not for the handshake era — pinning against it alone would leave the era
that current clients actually negotiate free to drift.
Update policy. When the gate fails, do not edit the constant blindly: read
the spec changelog between the two revisions, verify the server still behaves,
then move the constant, this section, README.de.md and
CHANGELOG.md together.
Testing
PYTHONPATH=src pytest tests/ -m "not live" # offline, respx-mocked
PYTHONPATH=src pytest tests/ -m live # hits the real API
python scripts/check_ruff_pin.py
ruff check src/ tests/ scripts/
ruff format --check src/ tests/ scripts/
python scripts/check_version_sync.pyChangelog
See CHANGELOG.md.
Contributing
Issues and pull requests are welcome. Please keep tools read-only, run ruff check and the offline test suite before submitting, and add a CHANGELOG.md entry under [Unreleased] for user-facing changes.
Maintainers: see PUBLISHING.md for the step-by-step PyPI release process (Trusted Publishing via GitHub Release).
Security
See SECURITY.md for the security posture, hardening controls, and how to report a vulnerability.
License
MIT for this server — see LICENSE. TERMDAT content remains subject to the Federal Chancellery's terms: name the source www.termdat.ch and inform the Terminology Section beforehand of purpose and manner of any reuse or republication (statement of 2026-08-21).
Author
Hayal Oezkan · github.com/malkreide
Credits & Related Projects
Data: TERMDAT, Swiss Federal Chancellery (BK).
Catalogue entry: I14Y data service
ff0c37eb…Discovery server: i14y-mcp
Portfolio index: swiss-public-data-mcp
Available Tools
7 toolsapi_statusARead-only
Availability of the TERMDAT API. Never returns silently empty.
Inputs: no named parameters. Returns: source, message, reachable, provenance, +3 more
check_termsARead-only
Check a list of terms against validated TERMDAT designations.
Intended for communication QA: verify that authority names, department titles and
abbreviations in a draft match the officially validated form. Each term is reported
as validated, found_unvalidated or not_found. Up to 25 terms per call; the
lookups run concurrently.
Inputs: terms (required), language. Returns: caveat, source, checked, results, +5 more
get_entriesARead-only
Fetch known TERMDAT entries by their numeric IDs, with full language variants.
Use this to re-retrieve an entry you already found via search_terms (its
entry_id), e.g. to pull all four national-language designations at once.
Inputs: entry_ids (required), in_language, out_language. Returns: hint, source, entries, returned, +6 more
list_classificationsBRead-only
List the 23 subject classifications (e.g. BILD = education), for classification_ids.
Inputs: language. Returns: kind, count, source, values, +3 more
list_collectionsARead-only
List the ~140 TERMDAT collections, for use as collection_ids filters.
Inputs: language. Returns: kind, count, source, values, +3 more
search_termsARead-only
Search TERMDAT for official designations of the Swiss Federal Administration.
Use this to look up the officially validated German/French/Italian/English name of an authority, department or legal act — for example to check how a body is named in another national language before citing it.
search_term is Lucene query syntax: * and ? wildcards and the ~ fuzzy
operator work. Matching is on whole words, so a compound is not found by its
parts — «Quellensteuer» does not match «Quellensteuerverordnung», but
«Quellensteuer*» does. Reach for a wildcard before concluding a term is absent.
Leave detail at True unless you want a bare hit list. With detail=False
the API omits languageDetails, and every entry comes back with an empty
variants — id, url, status and classification, but not a single designation.
That is a hit you cannot read a term from, from a tool whose purpose is terms.
Use it to count or to filter by classification, never to answer «what is this
called».
out_language adds a target language to every entry's variants — it is purely
additive and never filters the result set. fields is a comma-separated subset
of: Terminus, Name, Abbreviation, Phraseology, Definition, Note, Context, Source,
Metadata, Country, Comment; empty means Terminus, Name, Abbreviation, Phraseology,
Definition, Note, Source. By default the search spans all 23 subject
classifications; pass classification_ids or collection_ids to narrow it
(see list_classifications / list_collections).
Scope caveat: TERMDAT holds administrative nomenclature (authority names, titles of legal acts, abbreviations), not domain vocabulary — so a term may genuinely be absent. Establish that with a wildcard retry, not from a single empty result, and never fill the gap with a guessed designation.
Coverage caveat: the public API serves a subset of what termdat.bk.admin.ch shows, and the Federal Chancellery confirmed on 2026-08-21 that this is deliberate — the selection follows the needs of the federal administration's translators, and no fuller coverage is planned. Entries the website lists can be missing from the API entirely: not hidden by a filter, simply not served, so no query reaches them. So «not found here» means «not in the API», never «not in TERMDAT»: say which one you mean, and point at www.termdat.ch for the difference.
Inputs: search_term (required), detail, fields, in_language, +4 more. Returns: hint, source, entries, returned, +6 more
translate_termARead-only
Get the official equivalent of an administrative term in another national language.
Returns the preferred designation (sequence 1) plus accepted variants, per matching entry. Use this for authority names, department titles and titles of legal acts.
Matches only against designation fields, so a term merely mentioned in a
definition is never reported as an equivalent. term accepts Lucene wildcards;
on an empty result retry with term* before concluding there is no equivalent.
Inputs: term (required), max_results, to_language, from_language. Returns: hits, term, source, provenance, +4 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have clearly distinct purposes: searching, retrieving by ID, translating, batch QA, listing metadata, and status. search_terms and translate_term overlap somewhat since both query designations, but the descriptions make the intended use cases distinct enough for an agent to choose correctly.
Most tools follow a clear verb_noun pattern: search_terms, get_entries, translate_term, check_terms, list_collections, list_classifications. api_status is the one outlier, breaking the pattern by using noun_only style instead of something like get_status.
Seven tools is well-scoped for a read-only terminology lookup server. Each tool has a distinct role: search, retrieval, translation, QA checking, filter metadata, and API status, without redundant utilities.
The domain is Swiss administrative terminology lookup, and the tool surface covers the full lifecycle: discover entries, retrieve by ID, translate, validate batches, enumerate filters, and check API availability. There are no obvious dead ends or missing operations for a read-only API.
Maintenance
Related MCP Connectors
opendata.swiss MCP — Switzerland's federal open-data portal (CKAN catalogue).
Hosted MCP server for finding authoritative primary data sources and official portals.
Swiss federal law (Fedlex) and political data (LINDAS) for agents, every answer with sources
KVK Handelsregister AI Connect: hosted MCP server for the Dutch business register.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server connecting AI models to Swiss Federal Food Safety and Veterinary Office open data, enabling queries about food recalls, animal disease surveillance, food control results, and more.1134 PyPIMIT
- AlicenseAqualityBmaintenanceMCP server for querying Swiss intellectual property data (trademarks, patents, supplementary protection certificates) from the Swissreg register via natural language.1179 PyPIMIT
- AlicenseAqualityBmaintenanceMCP server for Swiss federal legislation metadata via Fedlex, enabling search and retrieval of act details with ELI URIs, SR numbers, and multilingual support.3Apache 2.0
- AlicenseBqualityDmaintenanceMCP server exposing all major Swiss official public APIs as native tools for any MCP-compatible AI agent.3412 npmMIT