hudu-mcp

hudu-mcp

hudu-mcp is a community Model Context Protocolserver for the Hudu IT documentation REST API. It exposes thedocumented v1 API — companies, assets, knowledge base articles, credentialrecords, IPAM, racks, website monitors, relations, integrations, the audit trailand the export triggers — as 89 MCP tools, and it withholds stored passwords andTOTP secrets from every response unless an operator has explicitly turned thatoff. It is aimed at MSPs and internal IT teams who want an assistant that canread and maintain their Hudu tenant over a local stdio connection, using an APIkey they scope themselves.

Before you install this, look at Hudu's own MCP server

Hudu ships a first-party MCP server built into the product. It is served fromyour own instance at https://<your-instance>/mcp, it authenticates with HuduOAuth rather than a long-lived API key, and it is enabled fromAdmin → External Apps → Model Context Protocol. Per Hudu's documentation itcovers articles (create, read, update), activity logs (read) and assets (readonly), and it deliberately excludes passwords, asset writes and deletions.

For a large number of people that is the better choice, and you should notinstall this project reflexively.

Use Hudu's server if what you need is article and asset reading with somearticle authoring, if you want per-user OAuth rather than a shared API key, ifyou need a hosted client to reach it over HTTP, or if you want something you canraise a support ticket about. Its narrower surface is a design decision, not anomission: a server that cannot delete anything and cannot read a password has amuch smaller worst case than this one.

Use hudu-mcp if you need the parts of the API Hudu's server does not cover —IPAM, racks, website monitors, relations, integration matchers, expirations,users, the audit trail — or if you need asset and password writes, or if you wantcapability gates you control from the environment rather than a fixed surface.

The two can coexist. Nothing here depends on Hudu's server being off.

Quick start

Requires Node.js 20 or newer and a Hudu API key.

npx @zenixsolutions/hudu-mcp --version

Configure your MCP client to launch it over stdio. The block below is thestandard shape and works in Claude Desktop, Claude Code and any other clientthat starts a local stdio server:

{
  "mcpServers": {
    "hudu": {
      "command": "npx",
      "args": ["-y", "@zenixsolutions/hudu-mcp"],
      "env": {
        "HUDU_BASE_URL": "https://hudu.example.com",
        "HUDU_API_KEY": "your-api-key",
        "HUDU_READ_ONLY": "1"
      }
    }
  }
}

That configuration registers 40 read tools and nothing that can change or deleteanything. Drop HUDU_READ_ONLY when you want writes; seeSecurity model before you do.

Verify a configuration without starting a session:

HUDU_BASE_URL=https://hudu.example.com HUDU_API_KEY=... npx @zenixsolutions/hudu-mcp --check
HUDU_BASE_URL=https://hudu.example.com HUDU_API_KEY=... npx @zenixsolutions/hudu-mcp --list-tools

--list-tools prints the tools that would be registered under the currentenvironment, plus the ones being withheld and why. It is the fastest way toconfirm a gate is set the way you think it is.

Longer walkthrough: docs/quickstart.md. Other installmethods: docs/installation.md.

Getting an API key

Create the key in Hudu at Admin → Basic Information → API Keys.

Hudu's own API documentation lists five scoping options on a key:

1. Access to passwords, covering all REST actions on them
2. Ability to perform destructive actions, meaning DELETE
3. Ability to perform exports
4. Whitelisted IP addresses
5. Company scopes

These options can only be configured when the key is created. They cannot bechanged afterwards; a different scope means a new key. Create the key with theleast this server needs and no more:

• Leave password access off unless you intend to setHUDU_ALLOW_PASSWORD_REVEAL=1.
• Leave destructive actions off unless you intend to setHUDU_ALLOW_DESTRUCTIVE=1.
• Leave export capability off unless you intend to set HUDU_ALLOW_EXPORTS=1.
• Set the IP allowlist if the machine running this server has a stable address.
• Set a company scope if the key only ever needs one customer.

A key created without password access is a harder boundary than any setting inthis software. HUDU_ALLOW_PASSWORD_REVEAL is a decision made by the operator inan environment variable, and it is enforced by code in this repository — codethat can have bugs, and that runs in the same process as a model readingattacker-influenced text. A key that Hudu will not let read /asset_passwords atall is enforced by Hudu, on the other side of the network, where nothing in thisprocess can reach it. Prefer that boundary whenever you can live with it.

Hudu's API documentation notes that a key can be created and deleted at anytime. Deleting the key is the fastest way to revoke this server's access.

Configuration

Everything is read from the environment. Nothing is read from disk, and nocredential is accepted as a tool argument.

The four gates are booleans. 1, true, yes and on (any case, surroundingwhitespace ignored) enable them; anything else, including an unset variable,leaves them off.

Setting HUDU_READ_ONLY and HUDU_ALLOW_DESTRUCTIVE together is rejected atstartup with exit code 78 rather than silently resolved. Read-only would win, butthe combination almost always means someone believes a delete is available whenit is not.

Invalid configuration reports every problem at once and exits 78, so amisconfigured install is fixed in one pass rather than one variable per restart.

Security model

Read SECURITY.md for the reporting process and the full model, anddocs/security.md for the threat model and residual risks.The short version:

Nothing permissive is on by default. Out of the box the server registers 70tools: reads, creates and updates. Deletions, password reveal and exports are allabsent until an operator sets the matching variable. A gated tool is notregistered at all rather than registered-and-refusing, because a tool a modelcannot see is a tool it cannot be talked into calling.

Four gates, all environment-only. HUDU_READ_ONLY,HUDU_ALLOW_DESTRUCTIVE, HUDU_ALLOW_PASSWORD_REVEAL and HUDU_ALLOW_EXPORTSare read in src/config.ts and nowhere else. There is no tool argument thatenables, overrides or softens any of them.

Passwords are withheld because of how the Hudu API is shaped. TheAsset_Password model lists password ("The actual password string") andotp_secret ("Secret key for one-time passwords") among its requiredproperties, and GET /asset_passwords returns an array of that model(docs/reference/spec-defects.md A1). A single unfiltered list call thereforereturns every credential and every TOTP seed the key can see. This server stripsthose two fields recursively from every tool result, centrally, inexecuteTool — leaving a placeholder so a model can tell a value exists — andrenders Markdown from the stripped payload rather than the raw record, andscrubs the rendered text by value behind that. The only exception ishudu_reveal_password, which needs HUDU_ALLOW_PASSWORD_REVEAL=1, an explicitconfirm: true, and one specific record id. There is no bulk reveal.

Destructive work needs two independent keys. The operator'sHUDU_ALLOW_DESTRUCTIVE decides whether the 16 destructive tools exist at all;the model's confirm: true argument then has to be supplied per call, with theimpact stated in the tool description. These are not redundant, and they are notequal: confirm is supplied by the model, so it is a prompt-level speed bump. Theenvironment flag is the gate a confused or manipulated agent cannot open. Thesame pair guards the two Admin-class export tools.

The API key's scope sits outside all of this and is the outermost boundary.See Getting an API key.

Tool surface

89 tools with every gate open, 70 with the defaults, 40 in read-only mode.

By operation class: 41 Read, 13 Create, 17 Update, 16 Destructive, 2Admin. hudu_reveal_password is classed Read because it does not modifyHudu, so it remains available in read-only mode whenHUDU_ALLOW_PASSWORD_REVEAL is also set — read-only mode restricts writes, notdisclosure.

Every tool, with its arguments and gates: docs/tool-reference.md.Task-oriented recipes: docs/user-guide.md.

Limitations

The Hudu v1 API cannot answer some questions that people reasonably expect it to,and this server reports those gaps rather than papering over them. The ones mostlikely to affect you:

• No collection endpoint returns a total count — no envelope, no total, noX-Total-Count, no Link header (C1). This server therefore emits neithertotal nor has_more. Read page_was_full and pagination_note, and nevertreat a full page as a complete list.
• Five collections have no pagination at all — networks, IP addresses, racks,rack items and uploads (C2). They return everything matching your filters inone response, and if that response is trimmed to fit the output budget there isno next page to ask for.
• A rack's contents cannot be listed (C4). No field or filter ties a rack itemto its rack.
• Exports can be started but never retrieved (C6). There is no statusendpoint and no download URL in this API version.
• File upload is not implemented (E1). The endpoints are multipart/form-dataand the contract documents no request body for them.
• A 403 is documented nowhere (A7), so a key-scope failure is hard todistinguish from a missing record.

The full list, with the evidence behind each item:docs/limitations.md.

Documentation

Contributing

See CONTRIBUTING.md. It states plainly which steps CI enforcesand which are convention. Pre-1.0, the tool surface is not stable: a minorversion may add, rename or remove tools.

Security reporting

Report vulnerabilities privately throughGitHub Security Advisories,not as a public issue. See SECURITY.md.

Licence

MIT. See LICENSE.

Disclaimer

This project is not affiliated with, endorsed by, or supported by HuduTechnologies, Inc. "Hudu" is used nominatively, to identify the product thissoftware interoperates with. Hudu is a trademark of its respective owner. Forsupport of the Hudu platform itself, including its own MCP server, contact Hudu.