HexDocs MCP
View SourceHexDocs MCP is a project that provides semantic search capabilities for Hex package documentation, designed specifically for AI applications. It consists of two main components:
- An Elixir package that downloads, processes, and generates embeddings from Hex package documentation
- A TypeScript server implementing the Model Context Protocol (MCP) that provides a searchable interface to the embeddings
Installation
Elixir Package
{:hexdocs_mcp, "~> 0.1.1", 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]}
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"
]
}
}
}
Requirements
- Ollama - Required for generating embeddings
- Run
ollama pull nomic-embed-text
to download the recommended embedding model - Ensure Ollama is running before using the embedding features
- Run
- Elixir 1.16+
- Node.js 22 or later (for the MCP server)
Configuration
By default, the mix hex.docs.mcp fetch
command stores all data in ~/.hexdocs_mcp
in the user's home directory. You can change this location by setting the HEXDOCS_MCP_PATH
environment variable:
# Example: Set custom storage location
export HEXDOCS_MCP_PATH=/path/to/custom/directory
This is also configurable in the MCP configuration for the server:
{
"mcpServers": {
"hexdocs-mcp": {
"command": "...",
"args": [
"..."
],
"env": {
"HEXDOCS_MCP_PATH": "/path/to/custom/directory"
}
}
}
}
Usage
Elixir Package
The SQLite database for vector storage and retrieval is created automatically when needed.
Fetch documentation, process, and generate embeddings for a package:
mix hex.docs.mcp fetch phoenix
Fetch documentation for a specific version:
mix hex.docs.mcp fetch phoenix 1.5.9
Use a specific embedding model when fetching:
mix hex.docs.mcp fetch --model all-minilm phoenix
Search in the existing embeddings:
mix hex.docs.mcp search --query "channels" phoenix
Pro Tip
When you need documentation for a specific package you don't have already, you can have the AI run the mix hex.docs.mcp fetch
command for you.
Acknowledgements
- hex2text - For the initial idea and as a reference
Development
This project uses mise (formerly rtx) to manage development tools and tasks. Mise provides consistent tool versions and task automation across the project.
Setting Up Development Environment
Install mise (if you don't have it already):
# macOS with Homebrew brew install mise # Using the installer script curl https://mise.run | sh
Clone the repository and setup the development environment:
git clone https://github.com/bradleygolden/hexdocs-mcp.git cd hexdocs-mcp mise install # Installs the right versions of Elixir and Node.js
Setup dependencies:
mise build
Development Tasks
Mise defines several useful development tasks:
mise build
- Build both Elixir and TypeScript componentsmise test
- Run all testsmise mcp_inspect
- Start the MCP inspector for testing the servermise start_mcp_server
- Start the MCP server (primarily for debugging)
Without Mise
If you prefer not to use mise, you'll need:
- Elixir 1.18.x
- Node.js 22.x
Then, you can run these commands directly:
# Instead of mise run setup_elixir
mix setup
# Instead of mise run setup_ts
npm install
# Instead of mise run build
mix compile --no-optional-deps --warnings-as-errors
npm run build
# Instead of mise run test
mix test
mix format --check-formatted
mix deps --check-unused
mix deps.unlock --all
mix deps.get
mix test
# Instead of mise run mcp_inspect
MCP_INSPECTOR=true npx @modelcontextprotocol/inspector node dist/index.js
AI Assistant Integration
This project includes custom instructions for AI assistants to help optimize your workflow when working with Hex documentation.
Example Custom Instructions
You can find sample custom instructions in the repository:
- Cursor rules - Custom rules for Cursor editor
- GitHub Copilot - Custom instructions for GitHub Copilot
Suggested Content
When working with Elixir projects that use Hex packages:
## HexDocs MCP Workflow
1. Use `vector_search` to find relevant documentation
2. For packages not in the database, fetch them with:
- `mix hex.docs.mcp fetch PACKAGE`
- For specific versions: `mix hex.docs.mcp fetch PACKAGE [VERSION]`
## Environment Setup
- Requires Ollama running with nomic-embed-text model pulled
- Default data location: `~/.hexdocs_mcp` (configurable via HEXDOCS_MCP_PATH)
- The SQLite database is created automatically when needed
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
This project is licensed under MIT - see the LICENSE file for details.