domustudio-mcp-server

An MCP server that exposes the Danea Domustudio public API — condomini, persone, fornitori — as tools an agent can call.

The API is read-only: its entire public surface is three GET endpoints. This server adds no write path, because there is none to add. Domustudio remains the system of record; anything that must change, changes there, by a human, in the product.

Requirements

• Node.js ≥ 22.12

• One Domustudio API key per archive (X-DANEA-API-KEY)

Related MCP server: Invoice4U MCP

Install it in another repository

The package is not on any registry — it installs straight from this repository, pinned to a release tag. One global install serves every repository on the machine.

npm install -g --allow-git=all "github:juriSacchetta/Domustudio-mcp#v0.4.0"

--allow-git=all is required on npm 12 and later, which ships allow-git = "none" as a default and otherwise refuses the install with EALLOWGIT. To stop passing it every time:

npm config set allow-git all

npm builds dist/ during install, so the machine needs nothing beyond Node ≥ 22.12 and access to this repository. npm 12 also prints install scripts blocked … (prepare: npm run build) — that warning is benign here: it refers to the consumer's tree, and the build has already run inside npm's isolated step for the git dependency. Confirm the install with:

test -f "$(npm root -g)/domustudio-mcp-server/dist/index.js" && echo installed

Do not run the entry point to "check" it: it is a stdio MCP server with no CLI, so it will start and wait for JSON-RPC on stdin rather than print anything.

A global install puts domustudio-mcp on your PATH, which is the name a shell-launched client needs — confirm with command -v domustudio-mcp. A GUI client is launched without your PATH and needs the absolute path instead:

echo "$(npm root -g)/domustudio-mcp-server/dist/index.js"

See Configure below for both. To upgrade, rerun the install command with a newer tag; every repository on the machine picks it up at once, which is the trade-off of a single global install.

Develop on it here

npm install
npm run build

Configure

The server reads its credentials from the environment, and falls back to a .env file in its working directory for anything the environment does not carry. DOMUSTUDIO_ARCHIVES is a JSON array — one API key addresses exactly one archive, and several archives may coexist.

Claude Code, one project

Add it at the default local scope: Claude Code stores that in ~/.claude.json under the project's path, so the server loads in this project only, stays private to you, and nothing lands in the repository.

claude mcp add domustudio -e DOMUSTUDIO_ARCHIVES='[{"name":"desa","api_key":"..."}]' \
  -- domustudio-mcp

The -- is required: everything after it is the server's own command line. A key passed this way lands in your shell history; to avoid that, drop the -e and put the key in a .env as below — the server finds it either way.

A committed .mcp.json

.mcp.json sits at the project root and is normally checked in, which is how a team shares one server definition — and exactly why the key must not appear in it. Leave the env block out and give each developer their own gitignored .env:

// .mcp.json — committed, no credentials
{
  "mcpServers": {
    "domustudio": { "command": "domustudio-mcp" }
  }
}

# .env at the project root — one per developer, never committed
printf '.env\n' >> .gitignore
printf 'DOMUSTUDIO_ARCHIVES=[{"name":"desa","api_key":"..."}]\n' >> .env
chmod 600 .env

Ignore it before you write it. .mcp.json is committed and .env must not be; nothing in this server can stop a consuming repository from committing one.

Claude Code launches the server with the project root as its working directory, which is where it looks. If your client launches it somewhere else, name the file outright in the .mcp.json entry — DOMUSTUDIO_ENV_FILE is a path, not a secret, so it is safe in a committed file. It has to arrive this way rather than from inside a .env, since it is what picks the file to read:

{ "mcpServers": { "domustudio": {
  "command": "domustudio-mcp",
  "env": { "DOMUSTUDIO_ENV_FILE": "/absolute/path/to/.env" }
} } }

Real environment variables always win over the file. Keep the array on one line, or wrap a multi-line one in single quotes — '[ … ]'.

Claude Desktop and other GUI clients

A GUI client is not launched from a shell and does not inherit your PATH, so the domustudio-mcp bin may not resolve. Give it Node and an absolute path. This file lives in your user profile, outside any repository, so the key may sit in it:

// claude_desktop_config.json — per user, never committed
{
  "mcpServers": {
    "domustudio": {
      "command": "node",
      // output of: echo "$(npm root -g)/domustudio-mcp-server/dist/index.js"
      "args": ["/absolute/path/to/domustudio-mcp-server/dist/index.js"],
      "env": {
        "DOMUSTUDIO_ARCHIVES": "[{\"name\":\"desa\",\"api_key\":\"...\"}]"
      }
    }
  }
}

Why ${DOMUSTUDIO_ARCHIVES} does not work

.mcp.json does expand ${VAR}, but supplying the value through .claude/settings.local.json env did not work: the server never started, and the failure reproduced with a control confirming the variable was present in the session. That is what #4 observed. Why the expansion missed it — an ordering question between settings env and .mcp.json loading — was not established, so treat the recipe as "this does not work", not as a mechanism you can reason around.

The symptom is worth recognising: an unexpanded variable is passed through as the literal text ${DOMUSTUDIO_ARCHIVES}, which is not JSON, so the server exits 1 and the client reports nothing more useful than domustudio (CONNECTION_CLOSED): "Connection closed". From 0.2.0 the server names that literal on stderr instead.

Exporting the variable from a shell rc file does make the expansion work, but it puts the key in a dotfile — no better than committing it. Prefer .env.

Variables

DOMUSTUDIO_BASE_URL exists for tests and for pointing at a mock; production should leave it unset. The default is HTTPS even though the OpenAPI servers entry says http://.

The key is never echoed in a tool result: an authentication failure names the archive and the header, not the value. The startup line on stderr names the .env it read, never its contents.

Tools

All five are annotated readOnlyHint: true, destructiveHint: false.

Every tool takes an optional archivio. With a single archive configured it may be omitted; with several, omitting it returns an error listing the names.

Every tool takes response_format: markdown (default) renders the main fields for reading, json returns the full API record except for condominium lists, which are compact in both formats. Integer enums are decoded to { codice, etichetta }.

What the API does not give you

Persone and fornitori have no identifier. Neither schema contains an id, and no endpoint accepts one, so there is no get_persona and no get_fornitore — a person or supplier is reached by filtering a list. The condominio id is the only stable handle the API exposes, and it is what domustudio_list_persone takes as condominio_id.

condominio_id is required and is sent to the API as CondGenID. For an archive-wide person search, follow all condominium list pages first, then call domustudio_list_persone for each id and follow each building's pagination.

Compact condominium lists (0.5.0 contract change)

domustudio_list_condomini defaults to pagina: 1, dimensione_pagina: 25 (maximum 100). If the building name or address is known, pass ricerca first. The case-insensitive local filter runs before pagination. Danea still returns the complete list upstream; only the selected compact page enters the MCP result.

Both text and structuredContent contain only id, intestazione, indirizzo, cap, citta, prov, and codFisc where present, with archivio in the envelope. conteggio counts the current page, totale counts all matches, and ha_altre_pagine is exact. When true, pass prossima_pagina as the next pagina with the same archive, filter and page size. Empty and out-of-range pages contain no elements and no next page. Each call reads the archive afresh; enumeration assumes the upstream list stays unchanged between calls.

Existing clients must follow pages instead of treating one response as a full inventory. Use domustudio_get_condominio for the complete record, including administrator and other details. There is no all-pages bypass for condominium lists. Other tools retain their existing contracts.

Persone and fornitori have no total count. Responses are bare JSON arrays. ha_altre_pagine is therefore a heuristic — true when the last page read was full — and is documented as such in the tool descriptions.

A page is reported to hold at most 100 records. The API caps PageSize there and says nothing when it does, so dimensione_pagina is refused above that rather than sent and silently truncated. One tutte_le_pagine call therefore reaches 5 000 records — 100 per page, 50 pages. npm run test:live measures the cap against a real archive. See docs/adr/0002.

Development

The suite runs against a local HTTP mock of the Domustudio API and needs no credentials. It covers the client (headers, 1-based paging, retry policy, the truncated-401), configuration and archive resolution, enum decoding, markdown rendering, every tool over an in-memory MCP transport, and the built binary over real stdio.

Running against the real API

Put real credentials in a .env at the repo root — it is gitignored:

printf 'DOMUSTUDIO_ARCHIVES=[{"name":"desa","api_key":"..."}]\n' > .env
chmod 600 .env
npm run test:live

Without DOMUSTUDIO_LIVE=1 those tests skip, so npm test stays green on a machine with no credentials. They only read, and assert on shapes and counts — no record content is printed.

Documentation

• CLAUDE.md — API facts an implementation has to know

• docs/adr/ — decisions and why they are hard to reverse

• CONTRIBUTING.md — the loop, the conventions, how to add a tool

• SECURITY.md — credential handling and how to report a vulnerability

• docs/read-only-guard.md — the hook that refuses mutating requests

• docs/verification-hook.md — the hook that runs lint and tests

Trademarks

Danea and Domustudio are trademarks of their respective owners. This project is an independent client of the Domustudio public API, is not affiliated with or endorsed by them, and is not supported by them.

License

MIT — see LICENSE. Copyright (c) 2026 Juri Sacchetta.