Hudu Server

Connect Claude AI to your Hudu IT documentation platform. Once installed, Claude can search, read, create, and update your Hudu knowledge base, assets, passwords, companies, and more — directly from any Claude interface.

---

What This Does

This server implements the Model Context Protocol (MCP), giving Claude secure, structured access to the Hudu REST API. It runs as a local stdio process that Claude Desktop or Claude Code launches on demand.

Available Tools

Category	Tools
Articles	list, get, create, update, delete, archive, unarchive
Assets	list (global + per-company), get, create, update, delete, archive, unarchive, move layout
Asset Layouts	list, get, create, update
Asset Passwords	list, get, create, update, delete, archive, unarchive
Companies	list, get, create, update, delete, archive, unarchive
Expirations	list, update, delete
Exports	list, get, create
S3 Exports	create
Flag Types	list, get, create, update, delete
Flags	list, get, create, update, delete
Folders	list, get, create, update, delete
Groups	list, get
IP Addresses	list, get, create, update, delete
Lists	list, get, create, update, delete
Magic Dash	list, upsert, delete (by title or ID), update positions
Matchers	list, update, delete
Networks	list, get, create, update, delete
Password Folders	list, get, create, update, delete
Photos	list, get, create, update, delete
Public Photos	list, get, create, update
Procedures	list, get, create, update, delete, kickoff, duplicate, create from template
Procedure Tasks	list, get, create, update, delete
Rack Storages	list, get, create, update, delete
Rack Storage Items	list, get, create, update, delete
Relations	list, create, delete
Uploads	list, get, delete
Users	list, get
VLANs	list, get, create, update, delete
VLAN Zones	list, get, create, update, delete
Websites	list, get, create, update, delete
Activity Logs	list, delete
Navigation	jump to card, jump to company
API Info	get version

---

Prerequisites

• Node.js 18 or newer — nodejs.org
• Claude Desktop or Claude Code
• A Hudu API key — generate one at Hudu Admin → Basic Information → API Keys

---

Installation

1. Clone and build

Clone the repo into the standard install location and build:

git clone https://github.com/Allied-Business-Solutions/hudu-mcp.git "$env:LOCALAPPDATA\Programs\HuduMCP"
cd "$env:LOCALAPPDATA\Programs\HuduMCP"
npm install
npm run build

This compiles the TypeScript source into dist/.

2. Configure Claude Desktop

Open (or create) your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the hudu entry under mcpServers:

{
  "mcpServers": {
    "hudu": {
      "command": "node",
      "args": ["C:/Users/YOUR_USERNAME/AppData/Local/Programs/HuduMCP/dist/index.js"],
      "env": {
        "HUDU_API_KEY": "your_api_key_here",
        "HUDU_BASE_URL": "https://your-instance.huducloud.com/api/v1"
      }
    }
  }
}

Replace YOUR_USERNAME with your Windows username, then fill in your API key and Hudu URL. Restart Claude Desktop.

3. Configure Claude Code

Add to ~/.claude/settings.json (or .claude/settings.json in your project):

{
  "mcpServers": {
    "hudu": {
      "command": "node",
      "args": ["C:/Users/YOUR_USERNAME/AppData/Local/Programs/HuduMCP/dist/index.js"],
      "env": {
        "HUDU_API_KEY": "your_api_key_here",
        "HUDU_BASE_URL": "https://your-instance.huducloud.com/api/v1"
      }
    }
  }
}

Replace YOUR_USERNAME with your Windows username, then fill in your API key and Hudu URL.

---

Environment Variables

Variable	Description
HUDU_API_KEY	Your Hudu API key (from Hudu Admin → Basic Information → API Keys)
HUDU_BASE_URL	Your Hudu instance API base URL, e.g. https://your-instance.huducloud.com/api/v1

See .env.example for a template.

---

Example Prompts

Once connected, you can ask Claude things like:

"Search Hudu for any articles about VPN setup and summarize what we have"

"Find all assets for Acme Corp and list their serial numbers"

"Create a new article called 'Windows 11 Deployment Guide' under the Acme Corp company with these steps: [paste steps]"

"Look up the password entry for the Acme firewall admin account"

"What procedures do we have documented for onboarding new employees?"

"Show me all SSL certificate expirations coming up in the next 30 days"

---

Troubleshooting

Tools don't appear in Claude Verify the config file is valid JSON and the path to dist/index.js is correct (e.g. C:/Users/YOUR_USERNAME/AppData/Local/Programs/HuduMCP/dist/index.js). Restart Claude Desktop after any config change.

HUDU_API_KEY is required error The env block in your Claude config is missing or the key name is wrong. Check that it's exactly HUDU_API_KEY.

HUDU_BASE_URL is required error Same — check that HUDU_BASE_URL is set and ends with /api/v1.

401 Unauthorized from Hudu Your API key is invalid or expired. Generate a new one from Hudu Admin → Basic Information → API Keys.

Node.js not found Install Node.js 18+ from nodejs.org and restart your terminal/Claude Desktop.

---

Development

npm run build    # compile TypeScript → dist/
npm run dev      # watch mode (recompiles on save)
npm start        # run the compiled server

File Structure

hudu-mcp/
├── src/
│   ├── api.ts       ← HTTP client helpers
│   ├── tools.ts     ← MCP tool definitions
│   └── index.ts     ← Server entry point + tool dispatch
├── dist/            ← Compiled output (git-ignored)
├── reference/
│   └── HuduRESTAPI.json  ← Hudu OpenAPI spec
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
└── README.md

---

Contributing

To add a new tool:

1. Add a Tool entry to the TOOLS array in src/tools.ts
2. Add the corresponding case to the callTool switch in src/index.ts
3. Run npm run build to verify it compiles

The Hudu API docs describe all available endpoints.

---

License

MIT