tink3r3r/mcp-kanji-decomposer

MCP Kanji Decomposer

An MCP server that decomposes Japanese kanji words/characters into component trees, enriched with KANJIDIC2 meanings and readings.

Features

Kanji Decomposition Tool

• —kanji_decomposer
• —Decomposes a Japanese word into per-character component trees using KanjiVG SVG data.
• —Input: word (string)
• —Output: chars array that mixes:
• —Kanji component nodes with char, variations, meanings, readings, composed_of
• —Non-kanji characters returned as strings

Example response shape (values abbreviated):

{
  "chars": [
    {
      "char": "漢",
      "variations": [],
      "meanings": ["..."],
      "readings": { "ja_on": ["..."], "ja_kun": ["..."] },
      "composed_of": [
        {
          "char": "氵",
          "variations": [],
          "meanings": ["..."],
          "readings": {},
          "composed_of": []
        }
      ]
    },
    "じ"
  ]
}

Health Check Endpoint

When running with HTTP or SSE transport, a health check endpoint is available at /healthz. It returns 200 OK with OK.

Configuration

1. 1.Open the Claude Desktop configuration file:
2. 2.macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. 3.Windows: %APPDATA%/Claude/claude_desktop_config.json

1. 1.Add a server entry (adjust the path to this repo):

{
  "mcpServers": {
    "mcp-kanji-decomposer": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-kanji-decomposer",
        "run",
        "mcp-kanji-decomposer"
      ],
      "env": {
        "MCP_SERVER_TRANSPORT": "stdio"
      }
    }
  }
}

You can also use the template in mcp.example.json.

1. 1.Replace uv with the absolute path if needed (use which uv).

Running Without uv (System Python)

From the repo root:

python3 -m mcp_kanji_decomposer.main

Then update the configuration to call python3 -m mcp_kanji_decomposer.main.

Environment Variables

MCP Server

• —MCP_SERVER_TRANSPORT: stdio (default), http, or sse
• —MCP_BIND_HOST: Host for HTTP/SSE (default 0.0.0.0)
• —MCP_BIND_PORT: Port for HTTP/SSE (default 8000)
• —MCP_QUERY_TIMEOUT: Timeout value available in config (default 30)

Auth (Optional)

Auth is enabled when ENV is not local or docker.

• —ENV: Set to local or docker to disable auth.
• —AUTH_GITHUB_CLIENT_ID, AUTH_GITHUB_CLIENT_SECRET: GitHub OAuth credentials.
• —SERVER_URL: Base URL used by the GitHub auth provider.

Docker

To run the server and MCP Inspector:

docker compose up --build

• —MCP endpoint: http://localhost:8000/mcp
• —Health check: http://localhost:8000/healthz
• —Inspector UI: http://localhost:6274

Development

uv sync
uv run mcp-kanji-decomposer

For HTTP transport:

MCP_SERVER_TRANSPORT=http MCP_BIND_PORT=8000 uv run mcp-kanji-decomposer

Data

This project ships with bundled kanji data in mcp_kanji_decomposer/data:

• —KanjiVG SVGs for component structure
• —KANJIDIC2 XML (gzipped) for readings and meanings