Content
<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](https://nucleoapp.com/application) at least once and sign in so it downloads your icons.
- **[Node.js](https://nodejs.org/) 22.5 or newer.**
- An MCP-capable assistant (for example [Claude Code](https://claude.com/claude-code)).
## 🚀 Install
```bash
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:
```bash
echo "$PWD/mcp.mjs"
```
### Claude Code
```bash
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:
```json
{
"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:
```json
{
"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):
```json
{
"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:
```bash
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:
```bash
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](https://nucleoapp.com/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.
