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.