urbandictmcp.

What it does

urbandictmcp exposes Urban Dictionary lookups as Model Context Protocol (MCP) tools. An MCP client such as VS Code, Claude Desktop, Codex, or a custom Python client launches it. The server runs locally over stdio and returns structured definition results that an AI assistant can call during a chat or agent workflow.

• No runtime npm dependencies; it uses Node.js built-in APIs.
• No database or background service.
• No API key required.
• It contacts Urban Dictionary's public JSON endpoints only when a lookup tool is called. Glossary rewriting makes no network requests.

Tools

• urban_dictionary_define: look up definitions for a word or phrase.
• urban_dictionary_random: fetch random definitions.
• urban_dictionary_defid: fetch a definition by Urban Dictionary definition ID.
• urban_dictionary_interpret: explain selected slang phrases in text with live definitions and original-text offsets.
• urban_dictionary_rewrite: convert text to plain language or slang using your own glossary, offline.
• shipmb_compile and shipmb_run (optional): compile or run supported English through ShipMBLang or ShipMBCompiler. These need a configured Python installation; the five dictionary tools work without Python.

Each call accepts up to 10,000 UTF-16 code units of text and 20 terms or glossary pairs, with 100 code units per phrase. The interpret tool explains the phrases you supply; it is not automatic slang detection.

{
  "text": "No cap, this works fr!",
  "direction": "to_plain",
  "glossary": [
    { "slang": "no cap", "plain": "honestly" },
    { "slang": "fr", "plain": "for real" }
  ]
}

This returns honestly, this works for real! as output, with the original offsets of each replacement. Use "direction": "to_slang" to go the other way.

Install and set up

You need Node.js 18 or newer. Nothing needs to be installed from npm, because the server only uses Node built-ins. Clone the repository and run the server:

git clone https://github.com/qramarq/urbandictmcp.git
cd urbandictmcp
node server.js

The server talks MCP JSON-RPC over stdin and stdout, so a quiet terminal is expected. Normally your MCP client launches it for you.

{
  "servers": {
    "urban-dictionary": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:\\path\\to\\urbandictmcp\\server.js"
      ]
    }
  },
  "inputs": []
}

{
  "mcpServers": {
    "urban-dictionary": {
      "command": "node",
      "args": [
        "C:\\path\\to\\urbandictmcp\\server.js"
      ]
    }
  }
}

Settings

• URBAN_DICTIONARY_API_BASE: override the API base URL.
• URBAN_DICTIONARY_TIMEOUT_MS: request timeout in milliseconds. Defaults to 10000.