{
  "markdown": "# hexpm-mcp\n\n[![CI](https://github.com/joshrotenberg/hexpm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/joshrotenberg/hexpm-mcp/actions/workflows/ci.yml)\n[![Hex.pm](https://img.shields.io/hexpm/v/hexpm_mcp.svg)](https://hex.pm/packages/hexpm_mcp)\n[![Docs](https://img.shields.io/badge/hexdocs-docs-purple.svg)](https://hexdocs.pm/hexpm_mcp)\n![Elixir](https://img.shields.io/badge/Elixir-1.17%2B-blueviolet)\n![OTP](https://img.shields.io/badge/OTP-28-blue)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n\nMCP server for querying [hex.pm](https://hex.pm) and [hexdocs.pm](https://hexdocs.pm) -- the Elixir/Erlang package registry and documentation hosting.\n\nBuilt with [Anubis MCP](https://hex.pm/packages/anubis_mcp) + [Bandit](https://hex.pm/packages/bandit) in Elixir.\n\n## Quick Start\n\nA 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):\n\n```json\n{\n  \"mcpServers\": {\n    \"hexpm\": {\n      \"type\": \"http\",\n      \"url\": \"https://hexpm-mcp.fly.dev/mcp\"\n    }\n  }\n}\n```\n\n## Installation\n\nThree ways to get it, depending on how you want to use it.\n\n### Standalone binary (recommended)\n\nA self-contained binary for macOS, Linux, and Windows. It bundles the Erlang\nruntime, so no Elixir toolchain is required.\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.sh | sh\n```\n\nThe installer resolves the latest release, picks the asset for your OS and\narchitecture, verifies its sha256, and installs to `~/.local/bin`. It will tell\nyou if that directory is not on your `PATH`.\n\nTo choose a different directory or pin a version, pass the flags through `sh`:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.sh | sh -s -- --install-dir /usr/local/bin\ncurl -fsSL https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.sh | sh -s -- --version v0.3.6\n```\n\nWindows uses the PowerShell equivalent:\n\n```powershell\niex (irm https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.ps1)\n```\n\nEvery [release](https://github.com/joshrotenberg/hexpm-mcp/releases) also\nattaches the archives and a combined `checksums-sha256.txt` if you would rather\ninstall by hand.\n\nVerify it works:\n\n```sh\nhexpm_mcp --version\n```\n\nSee [Usage](#usage) for the MCP client config, and\n[macOS: \"Apple could not verify hexpm_mcp\"](#macos-apple-could-not-verify-hexpm_mcp)\nif Gatekeeper blocks a browser-downloaded copy.\n\n### As an Elixir library\n\nFor the public API from iex or your own code, without running an MCP server:\n\n```elixir\ndef deps do\n  [{:hexpm_mcp, \"~> 0.3\"}]\nend\n```\n\n### From source\n\n```sh\ngit clone https://github.com/joshrotenberg/hexpm-mcp.git\ncd hexpm-mcp\nmix deps.get\n```\n\n## Features\n\n- 24 tools for searching, inspecting, comparing, auditing, and discovering hex.pm packages\n- 5 resources for structured package and discovery data access\n- 5 guided analysis prompts\n- HexDocs browsing (module listing, doc search, full module docs)\n- Curated package discovery via Elixir Toolbox (groups, trending, enriched search)\n- OSV.dev vulnerability checking\n- Mix.exs dependency auditing and upgrade checking\n- ETS-based response caching with configurable TTL\n- Dual transport: stdio (Claude Code/Desktop) and StreamableHTTP (remote)\n- Public Elixir API usable directly from iex\n\n## Tools\n\n### Package information\n| Tool | Description |\n|------|-------------|\n| `search` | Search packages by name/keywords with sorting and pagination |\n| `info` | Package metadata, description, links, download stats |\n| `versions` | Version history with retirement status |\n| `release` | Release details, publisher, dependencies, build tools |\n| `features` | Optional dependencies and extra metadata |\n| `dependencies` | Dependency list for a version |\n| `downloads` | Download statistics (all-time, recent, weekly, daily) |\n| `owners` | Package maintainers |\n| `readme` | README content as markdown |\n\n### Documentation browsing\n| Tool | Description |\n|------|-------------|\n| `docs` | Module listing (table of contents) from hexdocs.pm |\n| `doc_item` | Full documentation for a specific module |\n| `search_docs` | Search within a package's documentation |\n\n### Analysis\n| Tool | Description |\n|------|-------------|\n| `compare` | Side-by-side comparison of 2-5 packages |\n| `health` | Maintenance, popularity, quality, and risk assessment |\n| `audit` | Dependency risk audit (retired versions, staleness, bus factor, CVEs) |\n| `alternatives` | Find and compare similar packages |\n| `dep_tree` | Recursive dependency tree (BFS, max depth 5) |\n\n### Mix.exs analysis\n| Tool | Description |\n|------|-------------|\n| `audit_mix_deps` | Audit a deps list for staleness, retirement, CVEs, and bus factor |\n| `upgrade_check` | Check which deps have newer versions, flag breaking changes |\n\n### Discovery (Elixir Toolbox)\n\nCurated discovery via the [Elixir Toolbox](https://elixir-toolbox.dev) API. Project results carry GitHub/GitLab stats, a popularity score, and health signals not exposed by the raw hex.pm API.\n\n| Tool | Description |\n|------|-------------|\n| `toolbox_groups` | Browse the curated taxonomy of groups and categories |\n| `toolbox_group` | List the categories in a single group |\n| `toolbox_category` | Curated projects in a category (sortable by name or downloads) |\n| `toolbox_trending` | Trending Elixir packages |\n| `toolbox_search` | Search packages with popularity and health signals |\n\n## Example Output\n\n### Health check\n\n```\n# Health Check: req\n\n## Maintenance\n- Age: 4 years ago\n- Total versions: 52\n- Status: **Active**\n- Days since last release: 57\n\n## Popularity\n- All-time downloads: 11.5M\n- Recent (90 days): 1.6M\n- Weekly: 141.5K\n\n## Quality\n- Documentation: available\n- Licenses: Apache-2.0\n- Dependencies: 3 required, 4 optional\n- Elixir requirement: ~> 1.14\n\n## Risk\n- Maintainers: 1 (single maintainer!)\n- Retired versions: 0\n```\n\n### Package comparison\n\n```\n# Package Comparison\n\n| Metric          | req        | httpoison  | finch      |\n| --------------- | ---------- | ---------- | ---------- |\n| Downloads (all) | 11.5M      | 129.2M     | 54.1M      |\n| Downloads (90d) | 1.6M       | 1.6M       | 2.4M       |\n| Latest version  | 0.5.17     | 2.3.0      | 0.21.0     |\n| Last updated    | 2026-02-07 | 2025-11-14 | 2026-01-22 |\n| License         | Apache-2.0 | MIT        | MIT        |\n| Dependencies    | 7          | 1          | 5          |\n```\n\n### Dependency audit\n\n```\n# Dependency Audit: phoenix v1.8.5\n\nChecked 10 dependencies. 8 warning(s) across 7 package(s).\n\n- **bandit**: 1 retired version(s)\n- **jason**: single maintainer\n- **plug**: 2 retired version(s); 3 known vulnerability(ies)\n- **telemetry**: no issues\n```\n\n## Usage\n\n### Standalone binary (stdio)\n\nOnce [installed](#standalone-binary-recommended):\n\n```json\n{\n  \"mcpServers\": {\n    \"hexpm\": {\n      \"command\": \"hexpm_mcp\",\n      \"args\": [\"--transport\", \"stdio\"]\n    }\n  }\n}\n```\n\nThe binary defaults to stdio, so `args` can be omitted. Run `hexpm_mcp --help`\nfor the full option list.\n\nTo serve over HTTP instead, pass `--transport http`. MCP is served at `/mcp`:\n\n```sh\nhexpm_mcp --transport http --port 1234\n# MCP endpoint: http://localhost:1234/mcp\n```\n\n#### macOS: \"Apple could not verify hexpm_mcp\"\n\nThe binaries are not code-signed or notarized. macOS attaches a quarantine\nattribute to anything downloaded by a browser, and refuses to run an unsigned\nexecutable carrying it:\n\n> **\"hexpm_mcp\" Not Opened.** Apple could not verify \"hexpm_mcp\" is free of\n> malware that may harm your Mac or compromise your privacy.\n\nChoose **Done**, not Move to Trash, then clear the attribute:\n\n```sh\nxattr -d com.apple.quarantine /path/to/hexpm_mcp\n```\n\nThe System Settings route works too: Privacy & Security, then **Open Anyway**\nnext to the blocked-binary notice.\n\nThe installer above is unaffected, because `curl` does not set the quarantine\nattribute. Only browser downloads do, so installing with `curl` or `wget` avoids\nthis entirely. If you do download the tarball in a browser, extract it with\n`tar -xzf` from a terminal rather than double-clicking, since Archive Utility\npropagates the attribute to the extracted files.\n\n### From source (stdio)\n\nTo run from a checkout, e.g. for development:\n\n```json\n{\n  \"mcpServers\": {\n    \"hexpm\": {\n      \"command\": \"mix\",\n      \"args\": [\"run\", \"--no-halt\", \"--\", \"--transport\", \"stdio\"],\n      \"cwd\": \"/path/to/hexpm-mcp\"\n    }\n  }\n}\n```\n\n### iex\n\nThe public API is available directly from iex without the MCP server, either\nvia the [Hex dependency](#as-an-elixir-library) or straight from a checkout:\n\n```elixir\n$ MIX_ENV=test iex -S mix\n\niex> HexpmMcp.get_info(\"phoenix\")\n{:ok, %{\n  name: \"phoenix\",\n  description: \"Peace of mind from prototype to production\",\n  downloads: %{all: 148_100_000, recent: 2_600_000, week: 223_000, day: 13_000},\n  licenses: [\"MIT\"],\n  latest_stable_version: \"1.8.5\",\n  ...\n}}\n\niex> HexpmMcp.health_check(\"req\")\n{:ok, %{\n  name: \"req\",\n  maintenance: %{status: \"Active\", age: \"4 years ago\", days_since_release: 57},\n  popularity: %{all: 11_500_000, recent: 1_600_000, week: 141_000},\n  quality: %{has_docs: true, licenses: [\"Apache-2.0\"], required_deps: 3, optional_deps: 4},\n  risk: %{owner_count: 1, retired_count: 0},\n  ...\n}}\n\niex> HexpmMcp.compare_packages([\"plug\", \"bandit\"])\n{:ok, [\n  %{name: \"plug\", downloads_all: 156_000_000, dep_count: 3, ...},\n  %{name: \"bandit\", downloads_all: 9_900_000, dep_count: 5, ...}\n]}\n\niex> HexpmMcp.audit_mix_deps(~s({:phoenix, \"~> 1.7\"}, {:jason, \"~> 1.0\"}))\n{:ok, %{total_checked: 2, total_warnings: 1, results: [...]}}\n```\n\n## API Reference\n\nEvery function returns `{:ok, structured_map}` or `{:error, reason}`.\n\n```elixir\n# Search and lookup\nHexpmMcp.search(query, opts \\\\ [])\nHexpmMcp.get_info(name)\nHexpmMcp.get_downloads(name)\nHexpmMcp.get_owners(name)\nHexpmMcp.get_versions(name)\n\n# Version-specific (pass nil for latest)\nHexpmMcp.get_release(name, version \\\\ nil)\nHexpmMcp.get_dependencies(name, version \\\\ nil)\nHexpmMcp.get_features(name, version \\\\ nil)\n\n# Composite analysis\nHexpmMcp.compare_packages(names)\nHexpmMcp.health_check(name)\nHexpmMcp.audit_dependencies(name, version \\\\ nil)\nHexpmMcp.find_alternatives(name)\nHexpmMcp.dependency_tree(name, version \\\\ nil, opts \\\\ [])\n\n# Mix.exs analysis\nHexpmMcp.audit_mix_deps(deps_string)\nHexpmMcp.upgrade_check(deps_string)\n\n# HexDocs browsing\nHexpmMcp.get_readme(name, version \\\\ nil)\nHexpmMcp.get_docs(name, version \\\\ nil)\nHexpmMcp.get_doc_item(name, module, version \\\\ nil)\nHexpmMcp.search_docs(name, query, version \\\\ nil)\n\n# Elixir Toolbox (curated discovery)\nHexpmMcp.toolbox_groups()\nHexpmMcp.toolbox_group(group)\nHexpmMcp.toolbox_category(group, category, opts \\\\ [])\nHexpmMcp.toolbox_trending(opts \\\\ [])\nHexpmMcp.toolbox_search(query)\n```\n\n## Architecture\n\n```\niex / Elixir code                 MCP clients\n        |                              |\n   HexpmMcp (public API)         MCP Tools (thin wrappers)\n   returns {:ok, map}                  |\n        |                         calls HexpmMcp API\n   Client / HexDocs / OSV /      then Formatter -> markdown\n   Toolbox (internal clients)    then Response.text()\n```\n\n- **`HexpmMcp`** -- 25 public functions returning structured maps, usable from iex\n- **`HexpmMcp.Formatter`** -- markdown formatting for MCP tool output\n- **`HexpmMcp.Client`** -- Req-based hex.pm API client with rate limiting\n- **`HexpmMcp.HexDocs`** -- hexdocs.pm browsing (sidebar data parsing, HTML-to-markdown)\n- **`HexpmMcp.OSV`** -- OSV.dev vulnerability database client\n- **`HexpmMcp.Toolbox`** -- Elixir Toolbox client for curated package discovery\n- **`HexpmMcp.Cache`** -- ETS-based response cache with TTL and periodic sweeping\n- **`HexpmMcp.CLI`** -- Cheer command tree; turns argv into the server's configuration\n- **`HexpmMcp.MCP.StdioLifecycle`** -- exits 0 when a stdio client disconnects\n- **MCP Tools** -- thin wrappers calling the public API, registered via Anubis Server Components\n\n## Development\n\n```bash\n# Install dependencies\nmix deps.get\n\n# Run tests\nmix test\n\n# Full CI check\nmix format --check-formatted\nmix compile --warnings-as-errors\nmix credo --strict\nmix dialyzer\n\n# Run locally (HTTP on port 8765)\nmix run --no-halt\n\n# Run locally (stdio for MCP clients)\nmix run --no-halt -- --transport stdio\n```\n\n## License\n\nMIT\n",
  "bytes": 12425,
  "sha": "4bba5cbcdb730bb6cb39dc4fe95ea3aaf39d18c2f022bf0ce81c9cb67e74f00b",
  "repo_slug": "joshrotenberg/hexpm-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_joshrotenberg_hexpm_mcp_420402e6/readme"
}