HexDocs MCP enables semantic search of Hex package documentation directly from your editor. It combines an Elixir binary for downloading and embedding documentation with a TypeScript MCP server that integrates with AI coding assistants. Key features: - Semantic search across Hex package documentation using embeddings - Automatic downloading and processing of Elixir package docs - Integration with MCP-compatible clients including Cursor, Claude Desktop, and Continue - Local embedding generation via Ollama using models like mxbai-embed-large - Supports the Hex package manager ecosystem for Elixir

HexDocs MCP

HexDocs MCP is a project that provides semantic search capabilities for Hex package documentation, designed specifically for AI applications. It consists of two main components:

1. An Elixir binary that downloads, processes, and generates embeddings from Hex package documentation 2. A TypeScript server implementing the Model Context Protocol (MCP) that calls the Elixir binary to fetch and search documentation

> [!CAUTION] > This documentation reflects the current development state on the main branch. > For documentation on the latest stable release, please see the latest release page and the latest release branch.

Installation

MCP Client Configuration

The TypeScript MCP server implements the Model Context Protocol (MCP) and is designed to be used by MCP-compatible clients such as Cursor, Claude Desktop App, Continue, and others. The server provides tools for semantic search of Hex documentation. For a complete list of MCP-compatible clients, see the MCP Clients documentation.

Add this to your client's MCP json config:

{
  "mcpServers": {
    "hexdocs-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "hexdocs-mcp@0.5.0"
      ]
    }
  }
}

This command will automatically download the elixir binaries to both fetch_docs and search documentation. While the server handles downloading the binaries, you still need Elixir and Mix installed on your system for the HexDocs fetching functionality to work properly.

#### Smithery

Alternatively, you can use Smithery to automatically add the MCP server to your client config.

For example, for Cursor, you can use the following command:

npx -y @smithery/cli@latest install @bradleygolden/hexdocs-mcp --client cursor

Elixir Package

Alternatively, you can add the hexdocs_mcp package to your project if you don't want to use the MCP server.

{:hexdocs_mcp, "~> 0.5.0", only: :dev, runtime: false}

And if you use floki or any other dependencies that are marked as only available in another environment, update them to be available in the :dev environment as well.

For example floki is commonly used in :test:

{:floki, ">= 0.30.0", only: :test}

But you can update it to be available in the :dev environment:

{:floki, ">= 0.30.0", only: [:dev, :test]}

Requirements

Breaking Change: Model Migration (v0.6.0+)

⚠️ IMPORTANT: Version 0.6.0 introduces a breaking change with the default embedding model.

What changed:

To upgrade: 1. Pull the new model:

   ollama pull mxbai-embed-large
   

2. Your existing embeddings will be automatically cleared when you first run any command

3. Regenerate embeddings for your packages:

   mix hex.docs.mcp fetch_docs phoenix
   

Why this change: mxbai-embed-large provides significantly better semantic search quality and consistent dimensions across all platforms (Windows/macOS/Linux).

Configuration

Environment Variables

The following environment variables can be used to configure the tool:

| Variable | Description | Default | |----------|-------------|---------| | HEXDOCS_MCP_PATH | Path where data will be stored | ~/.hexdocs_mcp | | HEXDOCS_MCP_MIX_PROJECT_PATHS | Comma-separated list of paths to mix.exs files | (none) |

#### Examples:

# Set custom storage location
export HEXDOCS_MCP_PATH=/path/to/custom/directory
Configure common project paths to avoid specifying --project flag each time
export HEXDOCS_MCP_MIX_PROJECT_PATHS="/path/to/project1/mix.exs,/path/to/project2/mix.exs"

MCP Server Configuration

You can also configure environment variables in the MCP configuration for the server:

{
  "mcpServers": {
    "hexdocs-mcp": {
      "command": "...",
      "args": [
        "..."
      ],
      "env": {
        "HEXDOCS_MCP_PATH": "/path/to/custom/directory",
        "HEXDOCS_MCP_MIX_PROJECT_PATHS": "/path/to/project1/mix.exs,/path/to/project2/mix.exs"
      }
    }
  }
}

Usage

AI Tooling

The MCP server can be used by any MCP-compatible AI tool