# glyph-mcp

**English** · [Русский](README.ru.md)

An MCP server that gives Claude two web tools — `web_search` and `web_fetch` —
that return plain text instead of HTML. Pages are rendered through the
[glyph](https://github.com/k1y0miiii/glyph) terminal browser. The point is to
spend fewer tokens on web lookups.

Claude already has web tools, so why this one? Two reasons. glyph reduces a page
to just its readable text — no markup, scripts, navigation, or ads — and the
result is plain enough that you can grep or trim it before it reaches the model.
For a search that works out to roughly 8x fewer tokens.

![tokens per search](docs/tokens.png)

The trade-off is JavaScript: there isn't any. Single-page apps and dynamic
dashboards come back mostly empty, so the tool descriptions tell Claude to fall
back to its built-in fetch for those. Static pages, docs, articles, and plain
searches are where this earns its keep.

## Requirements

- `glyph` on your PATH (or its path in `GLYPH_BIN`). Install it from the glyph repo
  with `cargo install --locked --path crates/app` — it lands in `~/.cargo/bin`.
- Node 18 or newer.

## Add it to Claude Code

Published on npm as [`@k1y0mi/glyph-mcp`](https://www.npmjs.com/package/@k1y0mi/glyph-mcp),
so no build step is needed — `npx` runs it:

```
claude mcp add glyph -e GLYPH_BIN=$HOME/.cargo/bin/glyph -- npx -y @k1y0mi/glyph-mcp
```

Restart Claude Code and the two tools appear. To wire it up by hand instead, add
this to `.mcp.json` (project) or `~/.claude.json`:

```json
{
  "mcpServers": {
    "glyph": {
      "command": "npx",
      "args": ["-y", "@k1y0mi/glyph-mcp"],
      "env": { "GLYPH_BIN": "/Users/you/.cargo/bin/glyph" }
    }
  }
}
```

## Build from source

If you'd rather run it from a checkout instead of npm:

```
npm install
npm run build
claude mcp add glyph -e GLYPH_BIN=$HOME/.cargo/bin/glyph -- node /absolute/path/to/glyph-mcp/build/index.js
```

## Tools

- `web_search(query, max_chars?)` — run a search, get the results as text.
- `web_fetch(url, max_chars?)` — pull a single page as text.

`max_chars` caps the reply (default 8000). `GLYPH_BIN` points at the binary if
it isn't on your PATH.

## Notes

Arguments are passed to glyph via `execFile`, not a shell, so there's nothing to
inject. Each call times out at 30 seconds. `test/smoke.mjs` starts the server
over stdio and calls both tools — run it with `node test/smoke.mjs` after a
build.

## License

MIT.