211 lines
5.2 KiB
Markdown
211 lines
5.2 KiB
Markdown
# danbooru-mcp
|
||
|
||
An MCP (Model Context Protocol) server that lets an LLM search, validate, and get suggestions for valid **Danbooru tags** — the prompt vocabulary used by Illustrious and other Danbooru-trained Stable Diffusion models.
|
||
|
||
📖 **[Full User Guide](docs/user-guide.md)** — workflow walkthrough, tool reference, best practices, and common scenarios.
|
||
|
||
Tags are scraped directly from the **Danbooru public API** and stored in a local SQLite database with an **FTS5 full-text search index** for fast prefix/substring queries. Each tag includes its post count, category, and deprecation status so the LLM can prioritise well-used, canonical tags.
|
||
|
||
---
|
||
|
||
## Tools
|
||
|
||
| Tool | Description |
|
||
|------|-------------|
|
||
| `search_tags(query, limit=20, category=None)` | Prefix/full-text search — returns rich tag objects ordered by relevance |
|
||
| `validate_tags(tags)` | Exact-match validation — splits into `valid`, `deprecated`, `invalid` |
|
||
| `suggest_tags(partial, limit=10, category=None)` | Autocomplete for partial tag strings, sorted by post count |
|
||
|
||
### Return object shape
|
||
|
||
All tools return tag objects with:
|
||
|
||
```json
|
||
{
|
||
"name": "blue_hair",
|
||
"post_count": 1079908,
|
||
"category": "general",
|
||
"is_deprecated": false
|
||
}
|
||
```
|
||
|
||
### Category filter values
|
||
|
||
`"general"` · `"artist"` · `"copyright"` · `"character"` · `"meta"`
|
||
|
||
---
|
||
|
||
## Setup
|
||
|
||
### 1. Install dependencies
|
||
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
### 2. Build the SQLite database (scrapes the Danbooru API)
|
||
|
||
```bash
|
||
python scripts/scrape_tags.py
|
||
```
|
||
|
||
This scrapes ~1–2 million tags from the Danbooru public API (no account required)
|
||
and stores them in `db/tags.db` with a FTS5 index.
|
||
Estimated time: **5–15 minutes** depending on network speed.
|
||
|
||
```
|
||
Options:
|
||
--db PATH Output database path (default: db/tags.db)
|
||
--workers N Parallel HTTP workers (default: 4)
|
||
--max-page N Safety cap on pages (default: 2500)
|
||
--no-resume Re-scrape all pages from scratch
|
||
--no-fts Skip FTS5 rebuild (for incremental runs)
|
||
```
|
||
|
||
The scraper is **resumable** — if interrupted, re-run it and it will
|
||
continue from where it left off.
|
||
|
||
### 3. (Optional) Test API access first
|
||
|
||
```bash
|
||
python scripts/test_danbooru_api.py
|
||
```
|
||
|
||
### 4. Run the MCP server
|
||
|
||
```bash
|
||
python src/server.py
|
||
```
|
||
|
||
---
|
||
|
||
## Docker
|
||
|
||
### Quick start (pre-built DB — recommended)
|
||
|
||
Use this when you've already run `python scripts/scrape_tags.py` and have `db/tags.db`:
|
||
|
||
```bash
|
||
# Build image with the pre-built DB baked in (~30 seconds)
|
||
docker build -f Dockerfile.prebuilt -t danbooru-mcp .
|
||
|
||
# Verify
|
||
docker run --rm --entrypoint python danbooru-mcp \
|
||
-c "import sqlite3,sys; c=sqlite3.connect('/app/db/tags.db'); sys.stderr.write(str(c.execute('SELECT COUNT(*) FROM tags').fetchone()[0]) + ' tags\n')"
|
||
```
|
||
|
||
### Build from scratch (runs the scraper during Docker build)
|
||
|
||
```bash
|
||
# Scrapes the Danbooru API during build — takes ~15 minutes
|
||
docker build \
|
||
--build-arg DANBOORU_USER=your_username \
|
||
--build-arg DANBOORU_API_KEY=your_api_key \
|
||
-t danbooru-mcp .
|
||
```
|
||
|
||
### MCP client config (Docker)
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"danbooru-tags": {
|
||
"command": "docker",
|
||
"args": ["run", "--rm", "-i", "danbooru-mcp:latest"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## MCP Client Configuration
|
||
|
||
### Claude Desktop (`claude_desktop_config.json`)
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"danbooru-tags": {
|
||
"command": "python",
|
||
"args": ["/absolute/path/to/danbooru-mcp/src/server.py"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Custom DB path via environment variable
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"danbooru-tags": {
|
||
"command": "python",
|
||
"args": ["/path/to/src/server.py"],
|
||
"env": {
|
||
"DANBOORU_TAGS_DB": "/custom/path/to/tags.db"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Example LLM Prompt Workflow
|
||
|
||
```
|
||
User: Generate a prompt for a girl with blue hair and a sword.
|
||
|
||
LLM calls validate_tags(["1girl", "blue_hairs", "sword", "looking_at_vewer"])
|
||
→ {
|
||
"valid": ["1girl", "sword"],
|
||
"deprecated": [],
|
||
"invalid": ["blue_hairs", "looking_at_vewer"]
|
||
}
|
||
|
||
LLM calls suggest_tags("blue_hair", limit=3)
|
||
→ [
|
||
{"name": "blue_hair", "post_count": 1079908, "category": "general"},
|
||
{"name": "blue_hairband", "post_count": 26905, "category": "general"},
|
||
...
|
||
]
|
||
|
||
LLM calls suggest_tags("looking_at_viewer", limit=1)
|
||
→ [{"name": "looking_at_viewer", "post_count": 4567890, "category": "general"}]
|
||
|
||
Final validated prompt: 1girl, blue_hair, sword, looking_at_viewer
|
||
```
|
||
|
||
---
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
danbooru-mcp/
|
||
├── data/
|
||
│ └── all_tags.csv # original CSV export (legacy, replaced by API scrape)
|
||
├── db/
|
||
│ └── tags.db # SQLite DB (generated, gitignored)
|
||
├── plans/
|
||
│ └── danbooru-mcp-plan.md # Architecture plan
|
||
├── scripts/
|
||
│ ├── scrape_tags.py # API scraper → SQLite (primary)
|
||
│ ├── import_tags.py # Legacy CSV importer
|
||
│ └── test_danbooru_api.py # API connectivity tests
|
||
├── src/
|
||
│ └── server.py # MCP server
|
||
├── pyproject.toml
|
||
├── .gitignore
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
- Python 3.10+
|
||
- `mcp[cli]` — official Python MCP SDK
|
||
- `requests` — HTTP client for API scraping
|
||
- `sqlite3` — Python stdlib (no install needed)
|