mcp-server-serp-title-width

Check whether Chinese, Japanese and Korean page titles fit in Google search results, measured by rendered pixel width instead of character count. Ships as an MCP server (for AI agents) and a CLI (for builds and CI).

Documentation and background: adsandcode.com/en/open-source/serp-title-width

The problem

Site auditors and SEO plugins usually judge title length by counting characters, with limits around 60. That rule of thumb comes from Latin text. In the font Google uses for result titles, a CJK ideograph, a kana or a Hangul syllable is 22px wide, roughly twice an average Latin letter. Sixty of them come to 1320px, about twice the 652px desktop result column. A character-count check passes CJK titles that Google will cut in half.

Google says only that the title link is truncated as needed; its documentation gives no length in characters or pixels:

"the title link is truncated in Google Search results as needed" (Google Search Central, "Influencing your title links in search results")

So the width has to be measured.

Related MCP server: geo-tool-check

The model

Measured on 2026-09-18 on google.com with the zh-TW (Traditional Chinese, Taiwan) interface, Chrome on Windows, by reading the computed style of a result title and measuring glyph advances with a canvas in the same page.

Thresholds:

A digit costs about 0.56 of a full-width character, so "2026" takes the space of 2.2 ideographs. Capital letters are much wider than digits: an all-caps product name can push a title over the line that a character count, or a model that treats every Latin letter alike, says it fits.

The ASCII widths come from the font file (Arial Version 7.01 on Windows), in font units, measured with scripts/measure-arial.py and cross-checked three ways: Pillow at 2048px, the font's advance-width table read with fontTools, and measureText() on a Chrome canvas set to 22px arial. All 95 agree to within 0.0001px.

Re-measuring

If Google changes the title font size, every number above is wrong. Open a google.com results page in the interface language you care about and run this in the browser console:

(() => { const h = document.querySelector('a h3'), s = getComputedStyle(h);
  const c = document.createElement('canvas').getContext('2d');
  c.font = s.fontSize + ' ' + s.fontFamily;
  return { font: s.fontSize + ' ' + s.fontFamily,
           col: h.closest('div[data-hveid],div').getBoundingClientRect().width,
           cjk: c.measureText('貓').width, digit: c.measureText('0').width }; })()

If cjk is no longer 22, update EM and the thresholds in src/width.ts. If the font changes, regenerate the ASCII table with python scripts/measure-arial.py path/to/font.ttf. Do not measure with Pillow at 22px directly: hinting rounds each advance to a whole pixel (W becomes 21), while browsers use the unhinted widths.

Install

Requires Node.js 18 or later. No API keys, no network access.

MCP server

{
  "mcpServers": {
    "serp-title-width": { "command": "npx", "args": ["-y", "mcp-server-serp-title-width"] }
  }
}

CLI

npx -y -p mcp-server-serp-title-width serp-title-width ./public

or install it once with npm install -g mcp-server-serp-title-width and run serp-title-width.

CLI usage

serp-title-width <file|dir> ...           check <title> in .html/.htm files (directories are recursive)
serp-title-width --titles "t1" "t2" ...   check title strings
serp-title-width ... --json               machine-readable output
serp-title-width --selftest               run the ruler's positive and negative controls (use alone)

Example:

$ serp-title-width --titles "家常料理食譜站｜滷肉飯做法・便當菜色・120道快速晚餐" \
    "旗艦手機開箱｜SAMSUNG GALAXY S26 ULTRA VS GOOGLE PIXEL" "京都三天兩夜行程"
Checked 3 title(s). Safe <= 572px / edge > 630px / cut > 648px (Arial 22px, measured 2026-09-18).
------------------------------------------------------------------------------
[FAIL] (input 2)
   旗艦手機開箱｜SAMSUNG GALAXY S26 ULTRA VS GOOGLE PIXEL
   688.3px / 31.3 full-width characters / cut
   [FAIL] Cut: 688px (31.3 full-width characters), 40px over the 648px line. Desktop results will truncate it.
   [warn] Keyword zone (text before the first ？：、，) is 688px, wider than the 343px first line on mobile, so the line breaks inside it.

[warn] (input 1)
   家常料理食譜站｜滷肉飯做法・便當菜色・120道快速晚餐
   564.7px / 25.7 full-width characters / safe
   [warn] Keyword zone (text before the first ？：、，) is 565px, wider than the 343px first line on mobile, so the line breaks inside it.

[ok] (input 3)
   京都三天兩夜行程
   176.0px / 8.0 full-width characters / safe

------------------------------------------------------------------------------
Passed 2 / must fix 1

The second title is 47 characters, under a typical 60-character limit, and 688px wide. When scanning files, only titles with a finding are listed, each with its path under the folder you gave. Check a whole site at once so boilerplate tails across pages are detected.

What is read from disk:

• A directory is searched recursively for .html and .htm files. node_modules and anything starting with . (such as .git) are skipped, and symbolic links to folders are not followed.

• A file named explicitly is read whatever its extension, so serp-title-width page.php.txt works.

• A scan stops with exit code 2 after 20,000 HTML files, which usually means the path is not a site's build output.

• Only the <title> in the document head counts. Titles inside comments, <svg>, <math>, <script>, <style>, <template> and <noscript>, or after the head has ended, are ignored.

Exit codes

The selftest runs before every verdict. If the ruler cannot show that it still flags known-bad titles and passes known-good ones, it gives no verdict.

MCP tools

Each result has px, full_width_units (px / 22), tier, fails and warns (each finding is {rule, message}), plus boilerplate_tails for the set and a verdict of pass or fix. The server runs the selftest at startup and refuses to start if it fails.

Rules

Limitations

• Measured for one setting. google.com, zh-TW interface, Chrome on Windows, 2026-09-18. Other interface languages, browsers or operating systems can use different fonts and widths.

• Japanese and Korean were not measured separately. Kana and Hangul use the same full-width assumption (East Asian Width W), which matches how they are normally set, but nobody measured google.co.jp or google.co.kr for this model. Treat results for those languages as estimates.

• Kerning is not modelled. Widths are added one character at a time. Chrome also adjusts the space between some letter pairs, which makes text slightly narrower: the all-caps example above is 688.3px here and 686.7px in Chrome's canvas with its default kerning. Results err on the long side.

• Half-width characters outside ASCII are estimated at 12.2px. Their real Arial widths vary: é and – are 12.24px, “ 7.33px, ‘ 4.89px, Æ and ™ 22px.

• Ambiguous-width characters (East Asian Width A, for example ① ※ …) are counted as half width. Depending on the fallback font they can render wider.

• Google may display something else. It builds title links from several sources besides <title>, including headings, og:title, anchor text and WebSite structured data (which carries the site name), may replace a title it considers boilerplate or inaccurate, and may omit a site name that repeats the one already shown. Text that is not in your <title> can therefore appear in the result. A passing title is not a guarantee of what is shown.

• Emoji are not measured. Each emoji grapheme cluster counts as one full-width character when its first code point is full width or it carries the emoji presentation selector U+FE0F. Other emoji (such as flags, which Windows shows as two letters) count by their first code point.

• HTML reading is simple. The head <title> is found with patterns, not a full HTML parser. & < > " '   and numeric references are decoded; other named references are measured as written.

Port and parity

This is a TypeScript port of a Python implementation of the same model, which is not published. The port changes four things on purpose:

The shipped code can be switched back to the reference's behaviour, so scripts/parity.mjs --ref <title_check.py> checks two things: the code in that mode matches the reference exactly, and every difference in normal mode has one of the four causes above. Results against the current reference:

• 287 mixed titles (Traditional Chinese, Japanese kana, Korean Hangul, Latin, digits, full-width punctuation, emoji, whitespace edge cases): in the reference's mode, pixel widths, boilerplate tails and the ordered list of failed and warned rules are identical. In normal mode 27 verdicts differ, all with a named cause: colon-tail 21, separator-tier 4, zero-width 3 (one title can have more than one). Against the first reference, ascii-width also changes 4 verdicts, including the all-caps example above.

• Every code point from U+0020 to U+FFFF (63,456, surrogates excluded): in the reference's mode, the widths differ only where the two sides use different Unicode data. Against Python 3.10 (Unicode 13.0), 1,613 code points differ: 1,392 are unassigned (CPython before 3.12 reports East Asian Width F for unassigned code points), 143 were assigned after Unicode 13.0, and 78 changed from N to W in later Unicode (U+2630-U+2637, U+268A-U+268F, U+4DC0-U+4DFF). Against Python 3.12 (Unicode 15.0), 85 differ: the same 78 plus 7 newer assignments. This package follows the newer data from get-east-asian-width. In normal mode, 21 more differ, all zero-width characters.

License

MIT.

Maintainer

Built and maintained by Ads & Code.