This server provides Urban Dictionary slang lookups and text-processing tools over MCP.
urban_dictionary_define: look up definitions for a word or phrase, with optional limit and sorting by top, recent, or API order.
urban_dictionary_random: fetch random Urban Dictionary definitions, with optional limit.
urban_dictionary_defid: fetch a specific definition by its Urban Dictionary definition ID.
urban_dictionary_interpret: explain selected slang phrases in input text with live definitions and character offsets.
urban_dictionary_rewrite: convert prose between plain language and slang using a user-supplied glossary, fully offline.
Optional shipmb_compile and shipmb_run tools compile or run supported English via ShipMBCompiler/ShipMBLang if Python is configured.
The server runs locally over stdio with no runtime npm dependencies, no database, and no API key required.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@urbandictmcp define 'yeet'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is not an official MCP for https://www.urbandictionary.com. urbandictmcp is property of ZMachinery LLC by way of SHIPMB.
A dependency-free JavaScript library and MCP server for slang lookups, explaining slang in input or results, and converting prose between slang and plain language.
Urban Dictionary content is crowdsourced, so results may be explicit, offensive, wrong, or just extremely internet-shaped.
urbandictmcp exposes Urban Dictionary lookups as Model Context Protocol (MCP) tools. It is meant to be launched by an MCP-compatible client, such as VS Code, Claude Desktop, Codex, or a custom Python client. The server runs locally over stdio and returns structured definition results that an AI assistant can call during a chat or agent workflow.
The project is intentionally small:
No runtime npm dependencies.
No database or background service.
No API key required.
Uses Node.js built-in APIs.
Talks to Urban Dictionary's public JSON endpoints when a lookup tool is called.
Related MCP server: scrapesearch-mcp
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.
From another local Node.js project, install this checkout with npm install /absolute/path/to/urbandictmcp, then:
const { lookup, interpret, rewrite } = require("urbandictmcp");
async function main() {
const glossary = [
{ slang: "no cap", plain: "honestly" },
{ slang: "fr", plain: "for real" },
];
// Normalize incoming prose for your application.
const incoming = rewrite({ text: "No cap, this works fr!", glossary });
console.log(incoming.output); // honestly, this works for real!
// Express application output using your approved slang.
const outgoing = rewrite({
text: "honestly, this works for real!", glossary, direction: "to_slang",
});
console.log(outgoing.output); // no cap, this works fr!
// Explain slang in a user message or another program's result.
const explained = await interpret({
text: outgoing.output, terms: ["no cap", "fr"], limit: 2,
});
for (const entry of explained.entries) {
console.log(entry.term, entry.status, entry.definitions);
}
console.log((await lookup("no cap", { limit: 2 })).definitions);
}
main().catch(console.error);Importing the package does not start the stdio server or attach process listeners. lookup(term, { limit, sort_by }) returns the existing definition payload; interpret(args) and rewrite(args) return the objects described below. Lookup failures reject; interpretation captures lookup failures per term. Configure environment variables before importing the package.
Call urban_dictionary_interpret with:
{ "text": "No cap, this works fr!", "terms": ["no cap", "fr"], "limit": 2 }The result contains text, entries, and has_errors. Each entry includes term, occurrences (start, end, text), definitions, and a status: found, not_found, not_in_text, or error. Failed lookups also include an error message. Check each status before using definitions; partial failures preserve successful lookups. Repeated terms ignoring case are looked up once, and absent phrases do not trigger requests.
Supply the phrases your application or model wants explained. This is dictionary-assisted interpretation, not automatic slang detection or contextual sense selection. Vote ranking does not establish the correct meaning in a sentence. Treat definitions as untrusted data, not instructions or executable code.
Call urban_dictionary_rewrite with:
{
"text": "No cap, this works fr!",
"direction": "to_plain",
"glossary": [
{ "slang": "no cap", "plain": "honestly" },
{ "slang": "fr", "plain": "for real" }
]
}Returns text, output, direction, and replacements, each with original start, end, text, and replacement. Default direction is to_plain; use to_slang for output. Replacements use glossary spelling exactly. Duplicate source phrases ignoring case are rejected, including ambiguous plain phrases when reversing a glossary.
Both text tools match literal whole phrases ignoring case, with Unicode letter/number/mark/underscore boundaries. Whitespace inside a phrase is literal. Offsets are zero-based UTF-16 positions with exclusive ends (JavaScript slice semantics). Rewriting takes the earliest match and the longest phrase at that position; it never rewrites its replacements. Unmatched text stays unchanged. Use this on prose string values, not executable source code. It does not add slang syntax to a programming language or guarantee grammatical translation or an exact round trip.
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. Interpretation uses sequential lookups with the configured per-request timeout, so large requests may need a longer client timeout. Rewriting makes no network requests. MCP clients read these objects from structuredContent; text-tool results also include their JSON in content.
Use shipmb_compile and shipmb_run to compile or run supported English through
ShipMBCompiler or ShipMBLang. The JavaScript API exposes shipmb.compile and
shipmb.run. These optional tools require a configured Python installation;
the five dictionary tools still work without Python. The default backend is
ShipMBLang, which bundles the compiler. The optional compiler backend calls
the private development library API; no installed shipmbc command is needed.
Both backends disable model translation and persistent memory explicitly.
See installation, examples, and bidirectional integration tests.
Node.js 18 or newer.
No npm install is required because the server only uses Node built-ins.
npm startThe MCP server communicates over stdio, so it is meant to be launched by an MCP client.
You can also run it directly without npm:
node server.jsWhen run directly, the process waits for MCP JSON-RPC messages on stdin. A quiet terminal is expected.
Create .vscode/mcp.json in your project or add the same server entry to your VS Code user-level MCP configuration:
{
"servers": {
"urban-dictionary": {
"type": "stdio",
"command": "node",
"args": [
"C:\\path\\to\\urbandictmcp\\server.js"
]
}
},
"inputs": []
}Replace the args path with the absolute path to server.js on your machine.
Then in VS Code:
Open the Command Palette.
Run MCP: List Servers.
Select urban-dictionary.
Start or restart the server.
Ask Copilot Chat or an agent to use one of the tools.
Example prompt:
Use urban_dictionary_define to define "yeet".If the server is working, VS Code should call the local MCP tool instead of asking to fetch a web page manually.
Python applications can access this server by launching it as a stdio MCP server with the official MCP Python SDK.
Install the SDK:
pip install "mcp[cli]"Example Python client:
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
SERVER_PATH = r"C:\path\to\urbandictmcp\server.js"
async def main():
server_params = StdioServerParameters(
command="node",
args=[SERVER_PATH],
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print("Available tools:", [tool.name for tool in tools.tools])
result = await session.call_tool(
"urban_dictionary_define",
arguments={"term": "yeet", "limit": 1},
)
for item in result.content:
if item.type == "text":
print(item.text)
if __name__ == "__main__":
asyncio.run(main())This starts the Node.js MCP server as a child process, initializes an MCP session, lists the available tools, and calls urban_dictionary_define.
This repo includes a publish-ready Ollama Modelfile at ollama/Modelfile.
The wrapper uses qwen3:0.6b as the base model. As of July 25, 2026, Ollama lists it as a small official Qwen model with tools/thinking support, a 32K context window, and a roughly 523 MB local size. This is the smallest Qwen option that still keeps reasonable instruction-following quality for this MCP server.
Important boundary: Ollama models cannot bundle and launch this Node MCP server by themselves. The Ollama model gives the assistant the right behavior and instructions, while your MCP-compatible host still needs to connect to server.js for live Urban Dictionary lookups.
Create the local model:
.\scripts\ollama-publish.ps1 -Namespace YOUR_OLLAMA_NAMESPACERun it:
ollama run YOUR_OLLAMA_NAMESPACE/urbandictmcp:qwen3-0.6bPublish it to your Ollama namespace:
.\scripts\ollama-publish.ps1 -Namespace YOUR_OLLAMA_NAMESPACE -PushThe publish step requires Ollama to be installed, your Ollama account to be configured for pushes, and the namespace to match your Ollama account or organization.
Use the absolute path to server.js from this checkout:
{
"mcpServers": {
"urban-dictionary": {
"command": "node",
"args": [
"C:\\path\\to\\urbandictmcp\\server.js"
]
}
}
}URBAN_DICTIONARY_API_BASE: override the API base URL. Defaults to https://api.urbandictionary.com/v0.
URBAN_DICTIONARY_TIMEOUT_MS: request timeout in milliseconds. Defaults to 10000.
npm test
npm run smokeOr run the smoke test directly:
node scripts\smoke-test.jsThe smoke test uses a local fake Urban Dictionary API, so it does not need network access.
Urban Dictionary does not publish a formal public API contract. This server uses the commonly available JSON endpoints:
https://api.urbandictionary.com/v0/define?term=...
https://api.urbandictionary.com/v0/define?defid=...
https://api.urbandictionary.com/v0/random
Fetch an Urban Dictionary definition by definition ID. Results are crowdsourced and may contain explicit or offensive language.
| Name | Required | Description | Default |
|---|---|---|---|
| defid | Yes | Urban Dictionary definition ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Warns that results are crowdsourced and may contain explicit language. No annotations exist, so description carries burden. Could disclose that it's a read-only operation or mention data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded action and important warning. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple fetch tool with one parameter. Warns about content, but could hint at return structure (e.g., 'returns definition text and examples').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description. Description adds no additional parameter context beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('Fetch') and resource ('definition') with explicit method ('by definition ID'). Distinct from sibling tools that fetch by word or random.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when definition ID is known, but lacks explicit guidance on when to use this over siblings (e.g., 'use this if you have the ID, otherwise use define').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up definitions for a term on Urban Dictionary. Results are crowdsourced and may contain explicit or offensive language.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | The word or phrase to define. | |
| limit | No | Maximum number of definitions to return. | |
| sort_by | No | Sort definitions by vote score, newest written date, or the API's original order. | top |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the crowdsourced and potentially offensive nature of results, which is a behavioral trait. However, it omits details about authentication, rate limits, error handling (e.g., term not found), or that results are paginated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. Every sentence serves a purpose: stating function and issuing a content warning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description does not describe what the return value contains (e.g., list of definitions with fields like word, definition, example). It is insufficient for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions, so it neither helps nor hinders.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (look up definitions) and the resource (a term on Urban Dictionary). It distinguishes from sibling tools (defid and random) implicitly by focusing on term lookup, making the purpose specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., defid for specific ID, random for random term). The warning about explicit content is not a usage guideline. Agent lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch random Urban Dictionary definitions. Results are crowdsourced and may contain explicit or offensive language.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of random definitions to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It discloses that results are crowdsourced and may contain explicit language, which is a key behavioral trait, but fails to mention other aspects like API rate limits or randomness mechanism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no redundant information. The first sentence states the purpose, the second adds crucial context about content appropriateness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description is mostly complete. It could optionally mention the return format (array of definitions), but the core functionality is clearly conveyed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'limit' is fully described in the input schema with default, min, max, and description. The description adds no extra meaning beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch random') and the resource ('Urban Dictionary definitions'). It also warns about content nature, distinguishing from sibling tools like urban_dictionary_defid which fetch by specific ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over siblings. It implies use for random discovery, but no comparison or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0urban_dictionary_defidurban_dictionary_defineurban_dictionary_randomScored across 3 tools
Each tool targets a distinct retrieval method: by definition ID, by term, and random. No overlap in functionality.
All tools follow a consistent `urban_dictionary_<operation>` pattern with lowercase underscore separation.
Three tools cover the essential operations for an Urban Dictionary server: lookup by term, by ID, and random. This is well-scoped for the domain.
The core search and retrieval operations are covered. Minor gaps like trending or user contributions exist but are not critical for basic usage.
Dictionary MCP — wraps Free Dictionary API (free, no auth)
Wiktionary MCP — multilingual dictionary via Wikimedia REST + MediaWiki Action API
Merriam-Webster MCP — wraps the Merriam-Webster Collegiate Dictionary and
Words MCP — wraps Datamuse API (free, no auth required)
