# emoji-wisp-cli

stdio bridge to the emoji-wisp remote MCP service — plug emoji powers (search, mashup, emojiize) into Claude Desktop, Cursor or any MCP-stdio client.

[中文说明（README.zh-CN.md）](./README.zh-CN.md)

```
Claude Desktop ──stdio──> emoji-wisp-cli ──Streamable HTTP──> https://emoji.i68.ltd/mcp
```

This package is a thin bridge: tools and execution live on the remote MCP service (new remote tools need no CLI update).

## Tools (provided by the remote service)

| Tool | What it does |
|---|---|
| `search_emojis` | Search emojis/kaomoji/symbols by meaning |
| `get_emoji` | Details for one emoji (codepoints, mashup count), searchable by name |
| `random_emojis` | Random picks, filterable by category |
| `combine_emojis` | Mashup two emojis into an illustration (Google Emoji Kitchen, returns image URL) |
| `recommend_emojis` | LLM recommends emojis for an occasion |
| `suggest_replacements` | LLM suggests word→emoji replacements by mood & style |

## Use with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "emoji-wisp": {
      "command": "node",
      "args": ["/path/to/emoji-wisp-cli.mjs"],
      "env": { "EMOJI_WISP_MCP_URL": "https://emoji.i68.ltd/mcp" }
    }
  }
}
```

- One-file download: https://emoji.i68.ltd/cli/ (download `emoji-wisp-cli.mjs`, run with `node`, no npm install needed)
- Or install from npm: `npx emoji-wisp-cli`
- `EMOJI_WISP_MCP_URL` defaults to `https://emoji.i68.ltd/mcp`

## Requirements

- Node.js 24+
- A reachable emoji-wisp service (production: https://emoji.i68.ltd/mcp)

## License

MIT