Localize MCP

View Source

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

ToolPurpose
localize_searchKeyword search across modules, functions, and docs. Multi-word queries match tokens in any order.
localize_browseList modules in a documentation group.
localize_docFull @doc / @spec for a module or function.
localize_examplesCurated example snippets keyed by capability. Covers per-domain formatting and message translation (~t sigil, Gettext setup, Phoenix / LiveView integration).
localize_optionsAccepted options for a formatter, with allowed values.
localize_atomsClosed atom collections — locales, calendars, currencies, etc.
localize_errorsAll Localize.*Error modules with their :reason atoms.
localize_resolve_localeShow how Localize canonicalises a locale input.
localize_validateKind-aware binary-input validator.
localize_invokeExecute a whitelisted read-only function and return the result.
localize_term_grammarThe 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

License

Apache 2.0.