Hex.pm MCP

hexpm-mcp

[CI] [Hex.pm] [Docs] [Elixir] [OTP] [License: MIT]

MCP server for querying hex.pm and hexdocs.pm -- the Elixir/Erlang package registry and documentation hosting.

Built with snodo. It speaks MCP 2026-07-28, 2025-11-25, and 2025-06-18 over stdio and Streamable HTTP. See Protocol compatibility for what the older revisions lack.

It provides 24 tools, six prompts, and package resources. Tool arguments are validated against their JSON Schemas, each list fits on one page with cache hints, and prompt and resource arguments complete package names. The package_review prompt asks for its focus (quality, security, or upgrade) when the argument is omitted and the client supports elicitation. Otherwise the review covers all three.

The server sends instructions that name the tools to start with for each task. hexpm_mcp init installs it as a Claude Code and Codex plugin, together with a skill for evaluating, upgrading and auditing dependencies.

Quick Start

A public instance is running at https://hexpm-mcp.fly.dev/mcp. Add it to your MCP client config (Claude Desktop, Claude Code, or any MCP client):

{  "mcpServers": {    "hexpm": {      "type": "http",      "url": "https://hexpm-mcp.fly.dev/mcp"    }  }}

Protocol compatibility

A client that proposes a revision not in this table is offered 2025-11-25.

On 2025-11-25 and 2025-06-18:

• The server sends no requests to the client, so package_review without a focus returns a review across all three focuses instead of asking.
• HTTP is stateless. initialize issues no Mcp-Session-Id, every later request needs an MCP-Protocol-Version header, and GET and DELETE on /mcp return 405.

Upgrading from 0.3.7. 0.3.7 and earlier were built on anubis_mcp. They also served 2025-03-26 and 2024-11-05, and kept HTTP sessions with a GET event stream. Clients that depend on those can no longer connect.

Checked over stdio on 2026-09-26: Codex 0.157.1 negotiates 2025-06-18, and Claude Code 2.1.283 uses 2026-07-28.

Installation

Three ways to get it, depending on how you want to use it.

Standalone binary (recommended)

A self-contained binary for macOS, Linux, and Windows. It bundles the Erlang runtime, so no Elixir toolchain is required.

curl -fsSL https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.sh | sh

The installer resolves the latest release, picks the asset for your OS and architecture, verifies its sha256, and installs to ~/.local/bin. It will tell you if that directory is not on your PATH.

To choose a different directory or pin a version, pass the flags through sh:

curl -fsSL https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.sh | sh -s -- --install-dir /usr/local/bincurl -fsSL https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.sh | sh -s -- --version v0.3.6

Windows uses the PowerShell equivalent:

iex (irm https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.ps1)

Every release also attaches the archives and a combined checksums-sha256.txt if you would rather install by hand.

Verify it works:

hexpm_mcp --version

See Usage for the MCP client config, and macOS: "Apple could not verify hexpm_mcp" if Gatekeeper blocks a browser-downloaded copy. For Claude Code and Codex, hexpm_mcp init sets it up in one step.

As an Elixir library

For the public API from iex or your own code, without running an MCP server:

def deps do  [{:hexpm_mcp, "~> 0.3"}]end

From source

git clone https://github.com/joshrotenberg/hexpm-mcp.gitcd hexpm-mcpmix deps.get

Features

• 24 tools for searching, inspecting, comparing, auditing, and discovering hex.pm packages
• 5 resources for structured package and discovery data access
• 6 guided analysis prompts
• Server instructions naming the entry tools for each task
• A Claude Code and Codex plugin (MCP server, skill, and hook) installed by hexpm_mcp init
• HexDocs browsing (module listing, doc search, full module docs)
• Curated package discovery via Elixir Toolbox (groups, trending, enriched search)
• OSV.dev vulnerability checking
• Mix.exs dependency auditing and upgrade checking
• ETS-based response caching with configurable TTL
• Dual transport: stdio (Claude Code/Desktop) and StreamableHTTP (remote)
• Public Elixir API usable directly from iex

Tools

Package information

Documentation browsing

Analysis

Mix.exs analysis

Discovery (Elixir Toolbox)

Curated discovery via the Elixir Toolbox API. Project results carry GitHub/GitLab stats, a popularity score, and health signals not exposed by the raw hex.pm API.

Example Output

Health check

# Health Check: req
## Maintenance- Age: 4 years ago- Total versions: 52- Status: **Active**- Days since last release: 57
## Popularity- All-time downloads: 11.5M- Recent (90 days): 1.6M- Weekly: 141.5K
## Quality- Documentation: available- Licenses: Apache-2.0- Dependencies: 3 required, 4 optional- Elixir requirement: ~> 1.14
## Risk- Maintainers: 1 (single maintainer!)- Retired versions: 0

Package comparison

# Package Comparison
| Metric          | req        | httpoison  | finch      || --------------- | ---------- | ---------- | ---------- || Downloads (all) | 11.5M      | 129.2M     | 54.1M      || Downloads (90d) | 1.6M       | 1.6M       | 2.4M       || Latest version  | 0.5.17     | 2.3.0      | 0.21.0     || Last updated    | 2026-02-07 | 2025-11-14 | 2026-01-22 || License         | Apache-2.0 | MIT        | MIT        || Dependencies    | 7          | 1          | 5          |

Dependency audit

# Dependency Audit: phoenix v1.8.5
Checked 10 dependencies. 8 warning(s) across 7 package(s).
- **bandit**: 1 retired version(s)- **jason**: single maintainer- **plug**: 2 retired version(s); 3 known vulnerability(ies)- **telemetry**: no issues

Usage

Claude Code and Codex (hexpm_mcp init)

From 0.3.9, the binary installs itself as a plugin for Claude Code and Codex. The plugin bundles the MCP server with a skill that tells the agent when to use these tools: before adding a dependency, when upgrading, when auditing a project, and when writing code against a package's API. In Claude Code it also adds a hook that suggests audit_mix_deps and upgrade_check after an edit to mix.exs or mix.lock.

hexpm_mcp init --dry-runhexpm_mcp init

--dry-run shows the files and host commands without changing anything. init writes a local plugin marketplace, including a copy of the binary, to ~/.local/share/hexpm_mcp (or $XDG_DATA_HOME/hexpm_mcp). It then registers the marketplace with claude plugin and codex plugin. It configures whichever of the two is installed, and --host claude or --host codex picks one. It does not edit either host's configuration files directly. Reload plugins or start a new session afterwards.

Run hexpm_mcp init again after upgrading the binary to update the plugin.

If you already added hexpm-mcp as an MCP server by hand, init lists that entry when it finishes. The agent would otherwise see every tool twice, so remove one of them, for example with claude mcp remove hexpm.

To remove the plugin:

claude plugin uninstall hexpm@hexpm-local --scope userclaude plugin marketplace remove hexpm-localcodex plugin remove hexpm@hexpm-localcodex plugin marketplace remove hexpm-local

init is not supported on Windows yet.

Standalone binary (stdio)

Once installed:

{  "mcpServers": {    "hexpm": {      "command": "hexpm_mcp",      "args": ["--transport", "stdio"]    }  }}

The binary defaults to stdio, so args can be omitted. Run hexpm_mcp --help for the full option list.

To serve over HTTP instead, pass --transport http. MCP is served at /mcp:

hexpm_mcp --transport http --port 1234# MCP endpoint: http://localhost:1234/mcp

macOS: "Apple could not verify hexpm_mcp"

The binaries are not code-signed or notarized. macOS attaches a quarantine attribute to anything downloaded by a browser, and refuses to run an unsigned executable carrying it:

"hexpm_mcp" Not Opened. Apple could not verify "hexpm_mcp" is free of malware that may harm your Mac or compromise your privacy.

Choose Done, not Move to Trash, then clear the attribute:

xattr -d com.apple.quarantine /path/to/hexpm_mcp

The System Settings route works too: Privacy & Security, then Open Anyway next to the blocked-binary notice.

The installer above is unaffected, because curl does not set the quarantine attribute. Only browser downloads do, so installing with curl or wget avoids this entirely. If you do download the tarball in a browser, extract it with tar -xzf from a terminal rather than double-clicking, since Archive Utility propagates the attribute to the extracted files.

From source (stdio)

To run from a checkout, e.g. for development:

{  "mcpServers": {    "hexpm": {      "command": "mix",      "args": ["run", "--no-halt", "--", "--transport", "stdio"],      "cwd": "/path/to/hexpm-mcp"    }  }}

iex

The public API is available directly from iex without the MCP server, either via the Hex dependency or straight from a checkout:

$ MIX_ENV=test iex -S mix
iex> HexpmMcp.get_info("phoenix"){:ok, %{  name: "phoenix",  description: "Peace of mind from prototype to production",  downloads: %{all: 148_100_000, recent: 2_600_000, week: 223_000, day: 13_000},  licenses: ["MIT"],  latest_stable_version: "1.8.5",  ...}}
iex> HexpmMcp.health_check("req"){:ok, %{  name: "req",  maintenance: %{status: "Active", age: "4 years ago", days_since_release: 57},  popularity: %{all: 11_500_000, recent: 1_600_000, week: 141_000},  quality: %{has_docs: true, licenses: ["Apache-2.0"], required_deps: 3, optional_deps: 4},  risk: %{owner_count: 1, retired_count: 0},  ...}}
iex> HexpmMcp.compare_packages(["plug", "bandit"]){:ok, [  %{name: "plug", downloads_all: 156_000_000, dep_count: 3, ...},  %{name: "bandit", downloads_all: 9_900_000, dep_count: 5, ...}]}
iex> HexpmMcp.audit_mix_deps(~s({:phoenix, "~> 1.7"}, {:jason, "~> 1.0"})){:ok, %{total_checked: 2, total_warnings: 1, results: [...]}}

API Reference

Every function returns {:ok, structured_map} or {:error, reason}.

# Search and lookupHexpmMcp.search(query, opts \\ [])HexpmMcp.get_info(name)HexpmMcp.get_downloads(name)HexpmMcp.get_owners(name)HexpmMcp.get_versions(name)
# Version-specific (pass nil for latest)HexpmMcp.get_release(name, version \\ nil)HexpmMcp.get_dependencies(name, version \\ nil)HexpmMcp.get_features(name, version \\ nil)
# Composite analysisHexpmMcp.compare_packages(names)HexpmMcp.health_check(name)HexpmMcp.audit_dependencies(name, version \\ nil)HexpmMcp.find_alternatives(name)HexpmMcp.dependency_tree(name, version \\ nil, opts \\ [])
# Mix.exs analysisHexpmMcp.audit_mix_deps(deps_string)HexpmMcp.upgrade_check(deps_string)
# HexDocs browsingHexpmMcp.get_readme(name, version \\ nil)HexpmMcp.get_docs(name, version \\ nil)HexpmMcp.get_doc_item(name, module, version \\ nil)HexpmMcp.search_docs(name, query, version \\ nil)
# Elixir Toolbox (curated discovery)HexpmMcp.toolbox_groups()HexpmMcp.toolbox_group(group)HexpmMcp.toolbox_category(group, category, opts \\ [])HexpmMcp.toolbox_trending(opts \\ [])HexpmMcp.toolbox_search(query)

Architecture

iex / Elixir code                 MCP clients        |                              |   HexpmMcp (public API)         MCP Tools (thin wrappers)   returns {:ok, map}                  |        |                         calls HexpmMcp API   Client / HexDocs / OSV /      then Formatter -> markdown   Toolbox (internal clients)    then Snodo.Result.text()

• HexpmMcp -- 25 public functions returning structured maps, usable from iex
• HexpmMcp.Formatter -- markdown formatting for MCP tool output
• HexpmMcp.Client -- Req-based hex.pm API client with rate limiting
• HexpmMcp.HexDocs -- hexdocs.pm browsing (sidebar data parsing, HTML-to-markdown)
• HexpmMcp.OSV -- OSV.dev vulnerability database client
• HexpmMcp.Toolbox -- Elixir Toolbox client for curated package discovery
• HexpmMcp.Cache -- ETS-based response cache with TTL and periodic sweeping
• HexpmMcp.CLI -- Cheer command tree; turns argv into the server's configuration, or into the init subcommand
• HexpmMcp.Init -- hexpm_mcp init: writes the plugin marketplace and registers it through the claude and codex CLIs
• HexpmMcp.MCP.StdioLifecycle -- owns the stdio serving Task, drains requests on EOF, exits 0 on orderly disconnect, and reports transport failures with exit 1
• MCP Tools, Resources, and Prompts -- thin, JSON-shaped protocol components registered with Snodo.Server

Development

snodo and snodo_jsv come from Hex. To build against a local snodo checkout, set SNODO_PATH, for example SNODO_PATH=../snodo mix deps.get.

test/fixtures/mcp_tool_catalog.json holds the tool catalog, and the tests check the tool definitions against it. The acceptance tests seed domain data and exercise resources, tool failures, and argument validation through direct dispatch, stdio, and HTTP.

snodo's check with the official TypeScript client also runs against this server, over stdio and HTTP, with seeded domain responses. It needs a snodo checkout at ../snodo. Install its pinned Node dependencies once with npm ci --ignore-scripts in snodo/interop/official_client, then:

MIX_ENV=test mix compile --warnings-as-errorscd ../snodoHEXPM_MCP_BUILD_PATH=../hexpm-mcp/_build/test node interop/official_client/check_hexpm.mjs

# Install dependenciesmix deps.get
# Run testsmix test
# Full CI checkmix format --check-formattedmix compile --warnings-as-errorsmix credo --strictmix dialyzer
# Run locally (HTTP on port 8765)mix run --no-halt
# Run locally (stdio for MCP clients)mix run --no-halt -- --transport stdio

Under mix there is no standalone binary to install, so init from a checkout needs --binary pointing at a built or released hexpm_mcp:

mix run -- init --dry-run --binary /path/to/hexpm_mcp

The plugin sources are in priv/plugin/hexpm. test/hexpm_mcp/plugin_test.exs checks that every tool the skill names is served.

License

MIT