<div align="center" width="100%">
  <h2>🎨 nucleo-mcp</h2>
  <p>A local MCP server that gives your AI assistant 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://www.npmjs.com/package/@akashrajpurohit/nucleo-mcp"><img src="https://img.shields.io/npm/v/@akashrajpurohit/nucleo-mcp?logo=npm" /></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:

- 🏠 **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](https://nodejs.org/) 22.5 or newer, and Nucleo installed with your icons synced.

### 1. Sync your Nucleo library

Open the [Nucleo desktop app](https://nucleoapp.com/application) 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:**

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

<details>
<summary>Claude Desktop, Cursor, Windsurf, VS Code, and others</summary>

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

```json
{
  "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.

</details>

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

### 3. Check it works

```bash
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:

```bash
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](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](CONTRIBUTING.md) for the full guide and [ROADMAP.md](ROADMAP.md) for what is and is not planned.

```bash
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](https://nucleoapp.com/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](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.