Hudu MCP Server

Hudu MCP 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