cssnr/urban-dictionary-mcp repository overview

⁠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/⁠

⁠