Localize MCP

A Model Context Protocol (MCP) server for the Localize internationalisation library and its optional companions Calendrical and localize_web.

Exposes structured tools so AI agents — Claude Code, Claude Desktop, Codex, Zed, and any other MCP host — can discover and use the Localize API directly, without grepping the source.

Why

The Localize API surface is large — currencies, languages, scripts, territories, calendars, numbers, dates, times, intervals, durations, units, lists, messages, collation, locale displays, plural rules. AI agents that work with the library spend most of their tokens on discovery (which function takes which option, what atoms a locale resolves to, which exception covers which failure). This server turns each of those probes into a single typed tool call backed by BEAM introspection.

Tools

Tool	Purpose
`localize_search`	Keyword search across modules, functions, and docs. Multi-word queries match tokens in any order.
`localize_browse`	List modules in a documentation group.
`localize_doc`	Full `@doc` / `@spec` for a module or function.
`localize_examples`	Curated example snippets keyed by capability. Covers per-domain formatting and message translation (`~t` sigil, Gettext setup, Phoenix / LiveView integration).
`localize_options`	Accepted options for a formatter, with allowed values.
`localize_atoms`	Closed atom collections — locales, calendars, currencies, etc.
`localize_errors`	All `Localize.*Error` modules with their `:reason` atoms.
`localize_resolve_locale`	Show how Localize canonicalises a locale input.
`localize_validate`	Kind-aware binary-input validator.
`localize_invoke`	Execute a whitelisted read-only function and return the result.
`localize_term_grammar`	The JSON ↔ Elixir term grammar `localize_invoke` accepts.

Installation

Add to the mix.exs of a project that uses Localize:

def deps do
  [
    {:localize_mcp, "~> 0.1", only: :dev}
  ]
end

Then mix deps.get && mix compile, and start the server with:

mix localize_mcp

The server speaks MCP over stdio (JSON-RPC frames on stdin/stdout, logs on stderr) and introspects the Localize / Calendrical / localize_web versions your project pins, so the agent always sees exactly the API your code compiles against.

Wiring into an AI host

The Host configuration guide has copy-paste configuration for Claude Code, Claude Desktop, Codex CLI, ChatGPT, and Zed. The one-liner for Claude Code, run inside your project directory:

claude mcp add localize -- mix localize_mcp

Optional integrations

Calendrical — when loaded, non-Gregorian calendar atoms (:japanese, :hebrew, :islamic, …) appear in localize_atoms with collection: "calendars", and localize_doc resolves Calendrical.* module names.
localize_web — when loaded, the Phoenix / Plug helpers appear in localize_search and localize_browse under a "Web" group.

Both are detected at boot via Code.ensure_loaded?/1. The server runs identically with neither, either, or both present.

Safety

Live invocation is allowlisted. Anything not in priv/mcp/invocable.exs returns not_invokable.
No process state is mutated. Each localize_invoke call runs inside a Task.async/1 so the caller's process dictionary stays clean.
Per-call resource caps: 5 second timeout, 64 MB heap limit, 16 KB input cap on the term grammar.
Only the documented API is indexed: modules with @moduledoc false and functions with @doc false are invisible to search, browse, and doc tools.

Reading further

Usage guide — the end-to-end walk-through. Start here if you're new.
Host configuration guide — config for Claude Code, Claude Desktop, Codex CLI, ChatGPT, and Zed.

License

Apache 2.0.