MCP server

Give AI assistants emoji search, emoji for a sentence and reaction suggestions.

On this page

@emojisense/mcp is an MCP server (stdio) that gives an AI assistant three emoji tools. It works offline: the engine and the packs of all 11 languages ship inside the package. With a secret key, it also adds meaning results from the API.

Tools

Tool	Input	Use it to
`search_emoji`	`query`, `locale?`, `limit?` (10)	Find emoji for a keyword, slang, a name or a concept, for example “greatest of all time” → 🐐
`emoji_for_text`	`text`, `locale?`, `limit?` (5)	Pick emoji to add to a sentence. Also returns the text with the best emoji appended.
`suggest_reactions`	`text`, `locale?`, `limit?` (6)	Pick the emoji a reader would react with

locale is one of the bundled languages: en, ar, bn, es, fr, hi, id, pt, ru, tr, zh (default en). Every tool returns a short text and the same data as structured content. Each result has a source: alias (offline), semantic (API) or default (a generic reaction such as 👍, or 👀 for a question, that fills a short list). Offline reaction suggestions prefer the emoji people react with, the COMMON_REACTIONS list that the hosted API uses too.

Configure your client

Most MCP clients read a JSON file with an mcpServers object. Some call it servers and want "type": "stdio" on each entry.

{
  "mcpServers": {
    "emojisense": {
      "command": "npx",
      "args": ["-y", "@emojisense/mcp"]
    }
  }
}

{
  "mcpServers": {
    "emojisense": {
      "command": "npx",
      "args": ["-y", "@emojisense/mcp"],
      "env": {
        "EMOJISENSE_API_URL": "https://api.emojisense.com",
        "EMOJISENSE_SECRET_KEY": "sk_live_…"
      }
    }
  }
}

{
  "mcpServers": {
    "emojisense": {
      "command": "node",
      "args": ["/path/to/emojisense/packages/mcp/dist/cli.js"]
    }
  }
}

Set both variables or neither. With only one, the server writes a warning to stderr and runs offline. EMOJISENSE_API_URL must use https://, except http://localhost for development.

How it uses the API

search_emoji calls GET /v1/search in semantic mode only when the offline engine is unsure, with the same rule as the browser SDK. Confident queries cost nothing.
emoji_for_text and suggest_reactions send the text, at most 256 characters, to POST /v1/suggest-reactions. Message text never goes to the search endpoint, because the reactions endpoint never logs or caches text.
On a network error, a 4-second timeout, an HTTP error or overLimit, a tool returns the offline results. After overLimit, the server keeps asking: the shared edge cache still answers popular queries.

Try the tools

From a checkout, after pnpm --filter @emojisense/mcp build, open the tools in a browser UI with npx @modelcontextprotocol/inspector node packages/mcp/dist/cli.js.