Nucleo has tens of thousands of icons, and finding the right one usually means scrolling the app. This connects your assistant (Claude Code, Claude Desktop, Cursor, or any MCP client) straight to your own Nucleo library, so you can just ask "find me an outline shopping cart" or "save a user-profile icon into this project" and get the SVG back in seconds.

It reads the library the Nucleo desktop app already keeps on your computer:

• 🏠 Local and private. It reads files on your machine and makes no network calls. No accounts, no telemetry.
• 🔑 Only what you own. It shows icons your Nucleo license already includes. It does not unlock or fetch anything you have not purchased.
• 💾 Saves into your project only. The one thing it writes is an SVG, and only inside the folder your assistant is working in.

What you can ask

• "Search Nucleo for a shopping cart icon."
• "Show me the outline calendar icons at 24px."
• "Grab the glyph user icon from the Core pack and save it to ./src/icons."
• "Which Nucleo packs do I have?"

Setup

You need Node.js 22.5 or newer, and Nucleo installed with your icons synced.

1. Sync your Nucleo library

Open the Nucleo desktop app at least once and sign in, so it downloads your icons to your computer. That local library is what this server reads.

2. Add nucleo-mcp to your client

Claude Code:

claude mcp add nucleo --scope user -- npx -y @akashrajpurohit/nucleo-mcp

Claude Desktop: open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "nucleo": {
      "command": "npx",
      "args": ["-y", "@akashrajpurohit/nucleo-mcp"]
    }
  }
}

Cursor (~/.cursor/mcp.json) and Windsurf (~/.codeium/windsurf/mcp_config.json): add the same nucleo entry under mcpServers.

VS Code (GitHub Copilot) (.vscode/mcp.json): use the same entry under servers instead of mcpServers.

Any other client: register a stdio server whose command is npx -y @akashrajpurohit/nucleo-mcp.

Running from source instead of npm? Clone the repo, run npm install, and use node /absolute/path/to/nucleo-mcp/bin/nucleo-mcp.mjs as the command.

If your library is in a custom location, add "env": { "NUCLEO_DATA_PATH": "/path/to/icons" } to the entry (see Configuration).

3. Check it works

npx @akashrajpurohit/nucleo-mcp doctor

This checks your Node version, finds your Nucleo library, and reports how many icons and packs it can read. If everything is green, start a new session in your client and ask it to check the Nucleo status.

Tools

| Tool | What it does | |------|--------------| | nucleo_status | Confirms the library was found and reports icon and pack counts. | | nucleo_search | Finds icons by name and tags, ranked best first, with optional style and pack filters. | | nucleo_get | Returns one icon's SVG and details. | | nucleo_list_sets | Lists your icon packs. | | nucleo_save | Saves an icon into your project. |

nucleo_save only writes inside the folder your assistant is working in. It resolves the path and refuses to write anywhere else.

Command line

The nucleo-mcp command works on its own too, handy for a quick check without a client:

npx @akashrajpurohit/nucleo-mcp status
npx @akashrajpurohit/nucleo-mcp search "shopping cart"
npx @akashrajpurohit/nucleo-mcp get cart-shopping
npx @akashrajpurohit/nucleo-mcp save cart-shopping ./icons

Run nucleo-mcp --help for the full list.

Configuration

| Variable | Default | Description | |----------|---------|-------------| | NUCLEO_DATA_PATH | The Nucleo app's library folder | Folder holding data.sqlite3 and the sets/ directory. |

By default the server looks where Nucleo normally stores its library:

• macOS: ~/Library/Application Support/Nucleo/icons
• Windows: %APPDATA%\Nucleo\icons
• Linux: ~/.config/Nucleo/icons

Security & privacy

The server runs locally and makes no network calls. It reads only the icons your Nucleo license already includes, and it collects no telemetry. The single write it does (nucleo_save) stays inside your project folder. Full details are in SECURITY.md.

Troubleshooting

Run npx @akashrajpurohit/nucleo-mcp doctor first. If it says the library was not found:

• Open the Nucleo desktop app, sign in, and let your icons finish syncing.
• If your library is in a custom location, set NUCLEO_DATA_PATH to the folder that contains data.sqlite3 and the sets/ directory.

Contributing

Contributions are welcome. The project is small and has no build step. See CONTRIBUTING.md for the full guide and ROADMAP.md for what is and is not planned.

git clone https://github.com/AkashRajpurohit/nucleo-mcp.git
cd nucleo-mcp
npm install
npm test

Tests use Node's built-in runner and are fully offline. They build a throwaway SQLite fixture, so you do not need the Nucleo app installed to run them.

License and disclaimer

This project is not affiliated with, endorsed by, or associated with Nucleo or the Nucleo team. It is an independent tool that reads a Nucleo library you already own. "Nucleo" is a trademark of its respective owner, used here only to describe what the tool works with.

The icons stay under Nucleo's license. This tool does not change your rights to them, grant you icons you have not purchased, or let you redistribute them. Use the icons exactly as your Nucleo license permits.

Released under the MIT license (see LICENSE). Provided as-is, with no warranty. Because it reads Nucleo's local files, a future update to the Nucleo app could change where the library is stored; if that happens, nucleo_status will tell you the library was not found.