Kaomoji

What is Kaomoji?

Kaomoji is a Model Context Protocol (MCP) server that gives AI agents expressive, CLI-safe kaomoji (ASCII emoticons) for key interaction moments: thinking, celebrating, and apologizing. All kaomoji use only ASCII/half‑width characters, ensuring they render correctly in any terminal, IDE panel, or chat interface. It is built for developers using MCP‑compatible agents (e.g., Claude Desktop, Cursor, VS Code + GitHub Copilot, Windsurf, Zed, Continue.dev, Cline).

How to use Kaomoji?

Install Kaomoji via npm (npm install -g kaomoji-mcp) or use it directly with npx kaomoji-mcp. Configure it as an MCP server in your client's settings (e.g., claude_desktop_config.json, mcp.json, settings.json) using the stdio transport. Once connected, the agent will automatically know how to call the three tools at the appropriate moments; you can also load the react_with_kaomoji prompt to provide full behavior guidelines.

Key features of Kaomoji

• Three dedicated tools: thinking_kaomoji, celebrate_kaomoji, apologize_kaomoji
• A react_with_kaomoji prompt that teaches agents when and how to use each tool
• A kaomoji://catalog resource exposing the complete kaomoji database (75+ entries) as JSON
• All kaomoji are CLI‑safe (no full‑width or decorative Unicode characters)
• Works with many popular MCP clients: Claude Desktop, Claude Code, Cursor, VS Code + Copilot, Windsurf, Zed, Continue.dev, Cline, Smithery

Use cases of Kaomoji

• Provide real‑time progress feedback while an AI agent performs multiple sub‑tasks
• Celebrate task completion with subtle, moderate, or intense kaomoji based on context
• Politely apologize when search results are missing, an error occurs, or the user is dissatisfied
• Give agents a simple, universal way to express emotion across all text‑based interfaces

FAQ from Kaomoji

What tools does Kaomoji provide?

Kaomoji provides three tools: thinking_kaomoji (called before each sub‑task, accepts a phase description), celebrate_kaomoji (called after success, with intensity parameter), and apologize_kaomoji (called on failure, with reason parameter).

What runtime does Kaomoji require?

Kaomoji requires Node.js ≥ 20. It runs as a stdio MCP server and can be invoked via npx without installation, globally installed with npm, or cloned from GitHub and built locally.

Do I need to configure anything beyond client settings?

No. Once the server is referenced in your MCP client’s configuration (using stdio transport), the agent will automatically receive the server instructions on connection. Optionally, you can add the react_with_kaomoji prompt to your system prompt.

Is Kaomoji compatible with all terminals?

Yes. All kaomoji in the database are CLI‑safe—they contain only ASCII and half‑width characters, so they render without issues in any terminal, IDE panel, or chat interface.

What deployment options are available?

You can run Kaomoji via npx kaomoji-mcp (no install needed), install globally with npm, clone the repository and build locally, or deploy on Smithery using their CLI (npx @smithery/cli install kaomoji-mcp). All deployments use stdio transport.