Example prompts

• What does “gemas” mean according to KBBI?

• Apa arti kata “mempunyai”? Apa kata dasarnya?

• Explain “layarnya tidak makan” using KBBI.

Getting started

The server runs locally over stdio with uv’s uvx; no API key or account is needed. Most clients accept this standard config:

{
    "mcpServers": {
        "kbbi": {
            "command": "uvx",
            "args": ["kbbi-mcp"]
        }
    }
}

claude mcp add kbbi -- uvx kbbi-mcp

codex mcp add kbbi -- uvx kbbi-mcp

gemini mcp add kbbi uvx kbbi-mcp

code --add-mcp '{"name":"kbbi","command":"uvx","args":["kbbi-mcp"]}'

Tool: kbbi_lookup

Input

• query (string): a word or phrase

Example tool arguments:

{
    "query": "makan"
}

Output

Returns a JSON object:

• found (bool): whether entries is non-empty

• query (string): the trimmed query

• url (string): the KBBI page that was read

• entries (list): one item per headword; homographs such as makan¹ and makan² are separate entries

• suggestions (list of strings): similar headwords when nothing was found, if the page lists any (usually empty; see Limitations)

Each entry has:

• headword (string): syllable dots removed (ma.kan → makan)

• homograph (int | null): the superscript number, if any

• pronunciation (string | null): e.g. /gêmas/

• root_words (list of strings): e.g. ["punya"] for mempunyai

• senses (list), in page order, each with:

  • labels: {code, name, description} for word classes (v, n, …) and usage labels (ki, Tas, …)

  • gloss (string): the definition text

  • examples: {text, meaning}; -- or ~ in text stands for the headword, and meaning (string | null) explains idiomatic examples

Every key is always present (null or an empty list when absent), so the output shape is stable.

An empty query or a failed lookup (e.g. KBBI unreachable) is reported as an MCP tool error (isError: true) with a message, not as a JSON payload.

Example tool output:

{
    "found": true,
    "query": "gemas",
    "url": "https://kbbi.kemendikdasmen.go.id/entri/gemas",
    "entries": [
        {
            "headword": "gemas",
            "homograph": null,
            "pronunciation": "/gêmas/",
            "root_words": [],
            "senses": [
                {
                    "labels": [
                        {
                            "code": "a",
                            "name": "Adjektiva",
                            "description": "kata yang menjelaskan nomina atau pronomina"
                        }
                    ],
                    "gloss": "sangat jengkel (marah) dalam hati",
                    "examples": [
                        {
                            "text": "saya sangat -- pada anak itu karena selalu mengotori lantai",
                            "meaning": null
                        }
                    ]
                },
                {
                    "labels": [
                        {
                            "code": "a",
                            "name": "Adjektiva",
                            "description": "kata yang menjelaskan nomina atau pronomina"
                        }
                    ],
                    "gloss": "sangat suka (cinta) bercampur jengkel; jengkel-jengkel cinta",
                    "examples": [
                        {
                            "text": "-- aku melihat anak ini",
                            "meaning": null
                        }
                    ]
                }
            ]
        }
    ],
    "suggestions": []
}

Resource: kbbi://{query}

This server also exposes the same payload as a read-only MCP resource (application/json).

• kbbi://makan

For low-level debugging, a client would read it using resources/read with {"uri": "kbbi://makan"}.

Configuration

Optional environment variables:

• KBBI_TIMEOUT_SECONDS (default: 10.0): timeout for each request to KBBI

• KBBI_LOG_LEVEL (default: INFO): level of the server’s logs, written to stderr

• KBBI_BASE_URL (default: https://kbbi.kemendikdasmen.go.id): the KBBI site to query

For example, with Claude Code: claude mcp add kbbi -e KBBI_TIMEOUT_SECONDS=20 -- uvx kbbi-mcp. In the standard config, add an "env": {"KBBI_TIMEOUT_SECONDS": "20"} object next to "args".

Limitations

• Lookups are anonymous. KBBI shows etymology, related entries, and suggestions for missing words only to signed-in users, so they are not returned (suggestions is usually empty).

• Each lookup fetches https://kbbi.kemendikdasmen.go.id/entri/{query}. KBBI limits anonymous searches, so avoid rapid bulk lookups. Results are cached in memory while the server runs.

• The result depends on KBBI’s page markup; if KBBI changes it, parsing may break until this package is updated.

Debugging

Use the MCP Inspector:

npx @modelcontextprotocol/inspector uvx kbbi-mcp

Development

With uv installed, run the server over stdio from a checkout:

uv run kbbi-mcp

To point an MCP client at the checkout, use uv with --directory (an absolute path to your clone):

{
    "mcpServers": {
        "kbbi-dev": {
            "command": "uv",
            "args": ["--directory", "/path/to/kbbi-mcp", "run", "kbbi-mcp"]
        }
    }
}

Checks (see AGENTS.md):

uv sync --frozen --group dev
uv run ruff format .
uv run ruff check .
uv run ty check
uv run pytest

Tests use saved KBBI pages in tests/fixtures and make no network requests. Set KBBI_MCP_RUN_NETWORK_TESTS=1 to also run a live smoke test.

Related projects

• kbbi.mbt: a MoonBit library, CLI, and agent skill for KBBI. The parser and output schema of this server follow it.

• kbbi-python: a Python library and CLI for KBBI.

Disclaimer

This project is unofficial and is not affiliated with or endorsed by the Language Development and Cultivation Agency (Badan Bahasa) or KBBI Daring. Dictionary content belongs to its copyright holders; see KBBI’s legal notice. This server is meant for personal, non-commercial lookups. You are responsible for how you use the results.

License

BlueOak-1.0.0.