Content
English | [한국어](README.ko.md)
# danbooru-tag-rag-mcp
An MCP server that maps Korean natural-language descriptions to real Danbooru tags, with built-in hallucination filtering.
The **server** handles tag search and existence validation. **Decomposition, translation, tag selection, and natural-language generation** are delegated to the client LLM (Claude, etc.) via the bundled `danbooru_workflow` prompt.
## Architecture
```
User prompt (Korean)
│
▼
Client LLM ←── danbooru_workflow prompt (step-by-step instructions)
(Claude, etc.)
│ MCP tool calls
▼
MCP Server (this repo)
├── search_tags Vector search over general tags
├── search_character Character / copyright tag lookup
├── filter_existing Hallucination guard — drops invented tags
└── clean_character_tags Remove character-derived noise tags
│
▼
LanceDB (vector index) + ONNX multilingual-e5-large
```
- **Embedding model**: `intfloat/multilingual-e5-large` converted to ONNX (CPU inference; GPU optional for build only)
- **Index**: English tag name + Korean aliases per entry
- **Tag data**: Danbooru tags with Korean aliases, courtesy of [NyanTong](https://arca.live/b/aiart/139793445)
## Self-Hosting
The ONNX model and LanceDB index are **not bundled** — you must build them locally. The CSV is also not redistributed; download it directly from the author.
### Prerequisites
- Python 3.11+
- [uv](https://github.com/astral-sh/uv)
### Step 1 — Get the CSV
Download the Korean-annotated Danbooru tag CSV published by **NyanTong** on arca.live:
> <https://arca.live/b/aiart/139793445>
Place the file at the project root and name it **`danbooru-tags.csv`**.
### Step 2 — Convert the model and build the index
```bash
uv pip install -e ".[build]"
python scripts/setup.py # Works on any machine (~2 hours, varies by hardware)
```
**Faster GPU build (Windows):**
```bash
uv pip install onnxruntime-directml
python scripts/setup.py --gpu # (~7 min on an RTX 4060)
```
If no GPU is available, `--gpu` automatically falls back to CPU.
Downloads `intfloat/multilingual-e5-large` from HuggingFace, converts it to ONNX (`models/e5-large-onnx/`), and builds the LanceDB index (`data/lancedb_b/`).
If the model or index already exists, those steps are skipped automatically. Use `--force` to rebuild from scratch.
<details>
<summary>Run individual steps manually (advanced)</summary>
```bash
# Convert the model only
python scripts/convert_to_onnx.py
# Build the index only — CPU
python -m danbooru_mcp.core.builder b
# Build the index only — GPU (auto-detects DirectML → CUDA → CPU)
python -m danbooru_mcp.core.builder b --gpu
```
</details>
### Step 3 — Run the MCP server
```bash
# stdio transport (for MCP clients such as Claude Desktop)
uv run danbooru-mcp
# HTTP/SSE transport (for network clients)
uv run danbooru-mcp --http
```
### Step 4 — Register with a client
This MCP server runs over **stdio** and works with any MCP-compatible client.
Replace `/path/to/danbooru-tag-rag-mcp` with the absolute path where you cloned the repo.
#### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"danbooru-tag-rag": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/danbooru-tag-rag-mcp",
"danbooru-mcp"
]
}
}
}
```
Restart the app; verify the tool icon appears.
#### Claude Code
```bash
claude mcp add danbooru-tag-rag -- uv run --directory /path/to/danbooru-tag-rag-mcp danbooru-mcp
```
Run `/mcp` inside Claude Code to confirm the connection.
#### Codex
```bash
codex mcp add danbooru-tag-rag -- uv run --directory /path/to/danbooru-tag-rag-mcp danbooru-mcp
```
Run `/mcp` inside Codex to confirm. Config is stored in `~/.codex/config.toml`.
If `uv` is not on PATH, use its absolute path in the command.
### Environment Variables (optional)
| Variable | Default | Description |
|----------|---------|-------------|
| `DATA_DIR` | `<repo>/data` | LanceDB directory |
| `MODELS_DIR` | `<repo>/models` | ONNX model directory |
| `EMBEDDING_DEVICE` | auto | `cuda` or `cpu` for inference |
| `LLM_API_URL` | `http://localhost:8080/v1/chat/completions` | Local LLM endpoint (unused in standard MCP mode) |
## Known Limitations
- Some character tags with English-only names may appear in general-tag search results. They are rarely the top hit and can be filtered manually.
- Certain game-UI terms (danmaku, rhythm-game elements) may be classified as copyright entries rather than general tags.
- Rare characters absent from the CSV will not be found. Supply the exact English Danbooru tag directly in those cases.
## Credits
**Code**
[joykst96/danbooru-tag-rag](https://github.com/joykst96/danbooru-tag-rag) (MIT License)
Search and hallucination-filter logic is derived from this project. MCP interface and architecture redesign are new work in this repository.
**Tag data**
Korean Danbooru tag CSV by **NyanTong** ([arca.live post](https://arca.live/b/aiart/139793445)).
The CSV is **not redistributed** — please download it directly from the link above.
**License**: MIT — see [LICENSE](LICENSE).
