hudu-mcp
MCP (Model Context Protocol) server for Hudu IT documentation platform. Provides 39 tools and 6 resources for managing companies, assets, articles, passwords, websites, and more through any MCP-compatible client.
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
docker run -i --rm ghcr.io/wyre-ai/hudu-mcp:v1.4.4Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
HUDU_API_KEY=<secret> HUDU_BASE_URL=<value> MCP_TRANSPORT=<value> AUTH_MODE=<value> LOG_LEVEL=<value> claude mcp add io.github.wyre-ai-hudu-mcp -- docker run -i --rm ghcr.io/wyre-ai/hudu-mcp:v1.4.4在終端機中執行。
{ "mcpServers": { "io.github.wyre-ai-hudu-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/wyre-ai/hudu-mcp:v1.4.4" ], "env": { "HUDU_API_KEY": "<secret>", "HUDU_BASE_URL": "<value>", "MCP_TRANSPORT": "<value>", "AUTH_MODE": "<value>", "LOG_LEVEL": "<value>" } } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
MCP (Model Context Protocol) server for Hudu IT documentation platform. Provides 39 tools and 6 resources for managing companies, assets, articles, passwords, websites, and more through any MCP-compatible client.
MCP server for Hudu IT documentation — companies, assets, articles, passwords, and procedures.
HUDU_API_KEY REST access, or oauth — a thin,
authenticated proxy to a newer Hudu instance's own native MCP server[!IMPORTANT] Before you click: this server depends on
@wyre-technology/node-hudu, which is hosted on the GitHub Packages npm registry. GitHub Packages has no anonymous access — even though the package is public, everynpm installneeds a token. The cloud builder runsnpm installfor you, so you must give it one, or the build fails withnpm error 401 Unauthorized ... npm.pkg.github.com.
- Create a GitHub Personal Access Token with the
read:packagesscope (classic token). Any GitHub account works — you do not need to be a member of thewyre-technologyorg to read its public packages.- Add it as a build variable when prompted by the deploy flow:
- DigitalOcean App Platform → set an encrypted env var named
NODE_AUTH_TOKENwith scope Build Time to your PAT (theDockerfilereads it viaARG NODE_AUTH_TOKENto authenticatenpm ci).- Cloudflare Workers → set a build variable named
NODE_AUTH_TOKENto your PAT (Workers → Settings → Build → Variables and Secrets).
[!NOTE] The DigitalOcean target builds the full Docker image and runs the complete MCP server over HTTP — this is the recommended path for operators. This repo does not ship a
wrangler.json/Workers entrypoint, so for a self-hosted server prefer DigitalOcean or the prebuilt container image (ghcr.io/wyre-ai/hudu-mcp).
This project depends on @wyre-technology/node-hudu, published to the GitHub
Packages npm registry, which requires a token even for public packages.
Authenticate npm once before installing:
git clone https://github.com/WYRE-AI/hudu-mcp.git
cd hudu-mcp
# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token) # or a PAT with read:packages
npm install
npm run build
The repo's .npmrc already points the @wyre-technology scope at GitHub Packages and
reads the token from NODE_AUTH_TOKEN, so no further config is needed.
This server talks to Hudu in one of two ways. HUDU_AUTH_MODE picks between
them; if it's unset, the mode is auto-detected from whether HUDU_API_KEY
is set:
api_key (auto-selected when HUDU_API_KEY is set) — the classic mode.
This server calls Hudu's REST API directly via @wyre-technology/node-hudu and
implements all 39 tools itself, exactly as before. This is the mode every
existing deployment already uses, and it is 100% unchanged and unaffected by
everything below.
oauth (auto-selected when HUDU_API_KEY is not set) — for newer Hudu
instances that expose their own native MCP server (Hudu Admin -> External Apps
-> MCP), protected by interactive OAuth rather than a static API key. In this
mode hudu-mcp does not reimplement any tools; it acts as a thin, authenticated
proxy that forwards MCP requests straight through to {HUDU_BASE_URL}/mcp and
relays the responses back, so you automatically get whatever tool surface that
Hudu instance exposes.
The OAuth flow (RFC 9728/8414 discovery, RFC 7591 Dynamic Client Registration,
PKCE authorization_code, no client secret — this is a public client) runs the
first time a request needs a token:
hudu-mcp discovers the instance's OAuth metadata from
{HUDU_BASE_URL}/.well-known/oauth-protected-resource/mcp and
{HUDU_BASE_URL}/.well-known/oauth-authorization-server.client_id is cached).http://127.0.0.1:<ephemeral-port>/callback
catches the redirect and exchanges the code for tokens.~/.hudu-mcp/credentials-<hash-of-base-url>.json
(file mode 0600), and transparently refreshed on later runs — you should
only see the browser prompt again if the refresh token itself expires or
is revoked.Because this flow needs a browser that can reach a callback server bound to
127.0.0.1 on the machine running hudu-mcp, it works for stdio (always
local to the calling MCP client) and for a self-hosted http transport
running on the same machine you're browsing from — e.g. local testing on
localhost:8080. It does not work for an http transport deployed to a
remote host you don't have browser-level access to (a cloud VM, a
container, etc.): your browser can't reach that machine's own loopback
interface to complete the redirect, so the first-run authorization would
hang. This is unrelated to gateway mode (AUTH_MODE=gateway), which is a
stateless multi-tenant proxy with credentials injected per request via
headers and has no single user to run a browser flow for at all — setting
HUDU_AUTH_MODE=oauth together with AUTH_MODE=gateway is a startup error.
HTTP transport (both api_key and oauth) also requires CONDUIT_S2S_SECRET
or MCP_ALLOW_INSECURE_DEV=1. The dev flag binds 127.0.0.1 only. See
HTTP authentication. The stdio transport does not
use CONDUIT_S2S_SECRET.
Add to your claude_desktop_config.json:
{
"mcpServers": {
"hudu": {
"command": "node",
"args": ["/path/to/hudu-mcp/dist/entry.js"],
"env": {
"HUDU_BASE_URL": "https://docs.example.com",
"HUDU_API_KEY": "your-api-key"
}
}
}
}
For a newer Hudu instance with its own native MCP server (see
Authentication modes), omit HUDU_API_KEY and only set
HUDU_BASE_URL — hudu-mcp will print an authorization URL to the terminal the
first time it's launched:
{
"mcpServers": {
"hudu": {
"command": "node",
"args": ["/path/to/hudu-mcp/dist/entry.js"],
"env": {
"HUDU_BASE_URL": "https://docs.example.com"
}
}
}
}
/health stays unauthenticated and does not read credentials.
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
HUDU_BASE_URL=https://docs.example.com \
HUDU_API_KEY=your-api-key \
MCP_TRANSPORT=http \
MCP_HTTP_PORT=8080 \
npm start
Local HTTP without a service-to-service secret is development-only. It binds 127.0.0.1 and logs a warning:
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start
With MCP_TRANSPORT=http and a real CONDUIT_S2S_SECRET, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/mcp/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before Hudu credentials are read.
TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
-H "X-Hudu-Base-URL: $HUDU_BASE_URL" \
-H "X-Hudu-API-Key: $HUDU_API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
In AUTH_MODE=gateway, /mcp also requires X-Hudu-Base-URL and X-Hudu-API-Key. Those headers are the only credential source for that request. A missing header is HTTP 401 and does not fall back to HUDU_BASE_URL or HUDU_API_KEY in the environment.
Compose refuses to start when CONDUIT_S2S_SECRET is unset. The gateway service sets AUTH_MODE=gateway, does not inject HUDU_BASE_URL or HUDU_API_KEY, and publishes 127.0.0.1:8080:8080:
CONDUIT_S2S_SECRET=your-s2s-secret docker compose up
The image listens on 0.0.0.0 inside the container and still refuses to start without a real secret. Publish the port on loopback:
docker run \
-e CONDUIT_S2S_SECRET=your-s2s-secret \
-e AUTH_MODE=gateway \
-p 127.0.0.1:8080:8080 \
ghcr.io/wyre-ai/hudu-mcp
# Install dependencies
npm install
# Build
npm run build
# Run in development mode
npm run dev
# Clean build output
npm run clean
MCP server for Hudu IT documentation — companies, assets, articles, passwords, and procedures.
{ "mcpServers": { "io.github.wyre-ai-hudu-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/wyre-ai/hudu-mcp:v1.4.4" ], "env": { "HUDU_API_KEY": "<secret>", "HUDU_BASE_URL": "<value>", "MCP_TRANSPORT": "<value>", "AUTH_MODE": "<value>", "LOG_LEVEL": "<value>" } } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
發布者列出了以下環境變數:HUDU_API_KEY, HUDU_BASE_URL, MCP_TRANSPORT, AUTH_MODE, LOG_LEVEL。
Hudu 透過 stdio 在本機執行。
上次檢查時間:2026-11-09。 MCP server for Hudu IT documentation — companies, assets, articles, passwords, and procedures.