nucleo-mcp

<div align="center" width="100%"> <h2>🎨 nucleo-mcp</h2> <p>Give your AI assistant instant access to the <a href="https://nucleoapp.com">Nucleo</a> icons you already own.</p> <a target="_blank" href="https://github.com/AkashRajpurohit/nucleo-mcp/stargazers"><img src="https://img.shields.io/github/stars/AkashRajpurohit/nucleo-mcp" /></a> <a target="_blank" href="https://github.com/AkashRajpurohit/nucleo-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/AkashRajpurohit/nucleo-mcp" /></a> <img alt="Node version" src="https://img.shields.io/badge/node-%3E%3D22.5-339933?logo=nodedotjs&logoColor=white" /> <img alt="MCP server" src="https://img.shields.io/badge/MCP-server-1f1f1f" /> <img alt="Visitors" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fvc.akashrajpurohit.com%2Fc%2Fakash~gh~nucleo-mcp&query=count&style=flat&logo=github&label=Visitors&color=066da5" /> <a target="_blank" href="https://ko-fi.com/akashrajpurohit"><img src="https://img.shields.io/badge/Ko--fi-F16061?style=flat-square&logo=ko-fi&logoColor=white" /></a> <a target="_blank" href="https://akashrajpurohit.com/sponsors/?ref=nucleo-mcp"><img src="https://img.shields.io/badge/Sponsor-AkashRajpurohit-F16061?style=flat-square&logoColor=white" /></a> <a target="_blank" href="https://twitter.com/akashwhocodes"><img alt="follow on twitter" src="https://img.shields.io/twitter/follow/akashwhocodes.svg?style=social&label=@akashwhocodes" /></a> <br /> <br /> <p align="center"> <a href="https://github.com/AkashRajpurohit/nucleo-mcp/issues/new?template=bug_report.yml">Bug report</a> · <a href="https://github.com/AkashRajpurohit/nucleo-mcp/issues/new?template=feature_request.yml">Feature request</a> · <a href="https://github.com/AkashRajpurohit?tab=repositories">More projects</a> </p> </div> <hr />

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. Nothing leaves your machine.

✨ What it does and does not do

It does:

• Search all your Nucleo icons by name or meaning, ranked best-first.
• Return the SVG for any icon, in any style (outline, glyph, duo, colored) and size you own.
• Save an icon straight into your project folder.

It does not:

• Unlock premium icons. This is not a way around buying Nucleo. It only reads icons your own purchase and license already give you, from the library on your own machine. If you have not licensed an icon, it will not appear.
• Send your library, license key, or any data anywhere. There are no network calls and no accounts.
• Change your Nucleo library. It only reads from it.

📦 Before you start

You need:

• Nucleo, purchased and installed. Open the desktop app at least once and sign in so it downloads your icons.
• Node.js 22.5 or newer.
• An MCP-capable assistant (for example Claude Code).

🚀 Install

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

Then register it with your assistant. Note the full path to mcp.mjs — you will need it below:

echo "$PWD/mcp.mjs"

Claude Code

claude mcp add nucleo --scope user -- node "$PWD/mcp.mjs"

Claude Desktop

Open Settings → Developer → Edit Config (or edit claude_desktop_config.json directly) and add:

{
  "mcpServers": {
    "nucleo": {
      "command": "node",
      "args": ["/absolute/path/to/nucleo-mcp/mcp.mjs"]
    }
  }
}

Restart Claude Desktop.

Cursor

Open Settings → MCP → Add new global MCP server (or edit ~/.cursor/mcp.json) and add the same nucleo entry as above:

{
  "mcpServers": {
    "nucleo": {
      "command": "node",
      "args": ["/absolute/path/to/nucleo-mcp/mcp.mjs"]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json and add the same nucleo entry under mcpServers.

VS Code (GitHub Copilot)

Add it to .vscode/mcp.json in your workspace (or run MCP: Add Server from the Command Palette):

{
  "servers": {
    "nucleo": {
      "command": "node",
      "args": ["/absolute/path/to/nucleo-mcp/mcp.mjs"]
    }
  }
}

Any other MCP client

Register a stdio server that runs node /absolute/path/to/nucleo-mcp/mcp.mjs. That is all the server needs.

Once registered, start a new session and ask your assistant to "check the Nucleo status." It should report how many icons and packs it found. If it does, you are ready.

💬 How to use it

Just talk to your assistant. For example:

• "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?"

Behind the scenes it offers five tools your assistant uses automatically:

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.
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 will not write anywhere else on your computer.

🩺 If it can't find your icons

Run a quick check yourself:

node cli.mjs status

If it says the library was not found:

1. Open the Nucleo desktop app and make sure you are signed in and your icons have finished syncing.
2. If your library lives in a custom location, point the tool at it by setting NUCLEO_DATA_PATH to the folder that contains data.sqlite3 and the sets/ directory.

By default it looks where Nucleo normally stores its library:

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

🧪 Try it without an assistant

You can run everything from the terminal to see how it behaves:

node cli.mjs status
node cli.mjs search "shopping cart"
node cli.mjs get cart-shopping
node cli.mjs sets
node cli.mjs save cart-shopping ./icons

⚖️ Licensing and disclaimer

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

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

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