Urban Dictionary MCP

• Setup
  • Local
  • Remote
• Configure
• Development
• Building
• Support
• Contributing

MCP Server exposing the Urban Dictionary via the Model Context Protocol.

Setup

This can be run in Local CLI mode or Remote server mode.

Local

In CLI mode using uv.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "urban-dictionary": {
      "type": "local",
      "command": ["uvx", "urban-dictionary-mcp"]
    }
  }
}

In CLI mode using Python pip.

pip install urban-dictionary-mcp

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "urban-dictionary": {
      "type": "local",
      "command": ["urban-dictionary-mcp"]
    }
  }
}

Remote

With Docker run.

docker run --rm -p 80:8000 ghcr.io/cssnr/urban-dictionary-mcp:latest

With Docker Compose.

services:
  app:
    image: ghcr.io/cssnr/urban-dictionary-mcp:latest
    ports:
      - '80:8000'

With Python from source.

uv sync
uv run uvicorn urban_dictionary_mcp.server:app --app-dir src --host 0.0.0.0 --port 8000

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "urban-dictionary": {
      "type": "remote",
      "url": "http://localhost/mcp"
    }
  }
}

For a Docker Swarm + Traefik example see the docker-compose-swarm.yaml.

For a Portainer Deploy workflow see the .github/workflows/deploy.yaml.

Configure

This is for advanced configuration only.

Boolean True Values (case-insensitive): 1, on, t, true, y, yes

In Docker the cache path is /data/hishel_cache.db so you can mount /data as a volume.

Development

Sync project.

uv sync

Run local server.

run cli

Run remote server (live reload).

run dev

Point your client to: http://localhost:8000/mcp

Run remote Docker Compose (live reload).

run compose

Point your client to: http://localhost/mcp

You can set the PORT environment variable.

Building

Docker Image

To build and test the docker image run.

bash build.sh
docker compose up

Point your client to: http://localhost/mcp

Python Package

This builds the bdist and wheel, if you have a use for it...

run build

Support

If you run into any issues or need help getting started, please do one of the following:

• Report an Issue: https://github.com/cssnr/urban-dictionary-mcp/issues
• Q&A Discussion: https://github.com/cssnr/urban-dictionary-mcp/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/urban-dictionary-mcp/issues/new?template=1-feature.yaml
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY

Contributing

Please consider making a donation to support the development of this project and additional open source projects.

For a full list of current projects visit: https://cssnr.github.io/