Libredesk

npm CI License: MIT

Manage the knowledge base of your LibreDesk helpdesk from the terminal or from an AI assistant such as Claude.

The package ships two things:

• ldesk, a command line tool for help centers, articles and the knowledge LibreDesk's AI assistants answer from.
• An MCP server, so Claude and other MCP clients can do the same work for you: draft articles, review FAQ suggestions, or check why an article is not used by your AI assistant.

What you can do

• Write and edit help center articles in markdown. LibreDesk stores HTML; ldesk converts in both directions.
• Sync a folder of markdown files to articles. Run it again and only the changed articles are updated.
• Manage help centers and collections, and publish or unpublish many articles at once.
• Maintain AI snippets, import a web page as a snippet, and approve or reject FAQ suggestions.
• See which articles your AI assistants can use, and the reason for each one they can't.
• Look up the ids of agents, teams, inboxes and other settings, and send a raw request to any other endpoint.

Requirements

• Node.js 22.12 or newer.
• LibreDesk 2.9.2. Other versions may work; see API coverage.
• An API key and secret for a LibreDesk agent. The agent's role decides what you can do, for example help_center:manage for articles and ai:manage for snippets.

Install

npm install -g @spaceparrots/libredesk-mcp

Quick start

Log in once. ldesk checks the credentials and stores them as a profile; it asks for the secret without showing it.

ldesk login --url https://helpdesk.example.com --api-key <key>
ldesk status

Then work with your content:

ldesk help-center list
ldesk articles create 3 --title "Reset your password" --content @article.md
ldesk articles set-status 12 --status published
ldesk knowledge snippet create --title "Refunds" --content @refunds.txt

@article.md reads the value from a file. Run ldesk without arguments for an interactive menu, or add --help to any command for its options and examples.

Use it with Claude

Add the server to your MCP client. For Claude Code, run this in your project:

claude mcp add libredesk -- npx -y @spaceparrots/libredesk-mcp serve

For Claude Desktop, or to configure it by hand, add this to claude_desktop_config.json or to .mcp.json in your project:

{
  "mcpServers": {
    "libredesk": {
      "command": "npx",
      "args": ["-y", "@spaceparrots/libredesk-mcp", "serve"]
    }
  }
}

The server uses the login you stored with ldesk login, so the secret stays out of the config file. To pass credentials directly instead, add an env block with LIBREDESK_URL, LIBREDESK_API_KEY and LIBREDESK_API_SECRET. MCP server has all setup variants.

Then ask in plain language, for example:

• "List the articles in our help center that the AI assistant can't see, and why."
• "Draft an article about changing the delivery address from this email thread."
• "Go through the pending FAQ suggestions and approve the ones that are correct."

If the client can't connect, run ldesk doctor in the folder where the client runs. It starts the server the same way the client does and tells you what went wrong.

Safe by default

• Drafts first. New articles are drafts. Publishing, moving articles and collections, taking a help center offline, enabling FAQ learning, changing a help center's custom code and deleting are separate steps that ask for confirmation.
• Separate tools for risky actions. Over MCP, publishing and deleting live in their own tools, libredesk_publish and libredesk_delete, so your client can ask you before each one. Edits made with the other tools take effect at once, so editing an already published article changes the live page. See Permissions.
• Updates keep your data. LibreDesk replaces a whole record on every update. ldesk reads the current record first, so changing a title never resets the content or the AI setting.
• Secrets stay hidden. The API secret is stored in ~/.libredesk-mcp/config.json (file mode 0600 on macOS and Linux) and is masked in all output, also when a server echoes it back.
• Local files stay local. Over MCP, sync reads only below the server's folder (or LIBREDESK_SYNC_ROOT) and skips symbolic links, and LIBREDESK_MCP_PROFILES limits which stored profiles a server may use. ldesk doctor asks before starting a server command that the current folder can change.

Documentation

• CLI reference: logging in, profiles, every command, syncing a folder.
• MCP server: setup for Claude Code and Claude Desktop, tools, permissions.
• API coverage: which LibreDesk version is targeted and which endpoints are undocumented.
• Development: building, testing against a local LibreDesk, adding an endpoint.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md. To report a security problem, see SECURITY.md.

This project is not affiliated with LibreDesk. Many of the endpoints it uses are not part of LibreDesk's documented API and may change between LibreDesk releases.

License

MIT