What It Does 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. 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. Requirements Node.js 18 or newer. No npm install is required because the server only uses Node built-ins.

Run npm start The 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.js When run directly, the process waits for MCP JSON-RPC messages on stdin. A quiet terminal is expected.

VS Code Setup 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:\your\user\file\path\locally” ] } }, “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 Client Access 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:\your\user\file\path\locally”

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.

Generic MCP Client Config Use the absolute path to server.js from this checkout:

{ “mcpServers”: { “urban-dictionary”: { “command”: “node”, “args”: [ “C:\your\user\file\path\locally” ] } } } Environment Variables 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. Test npm run smoke Or run the smoke test directly:

node scripts\smoke-test.js The smoke test uses a local fake Urban Dictionary API, so it does not need network access.

Notes 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