ahnlich-mcp

Ahnlich MCP

An MCP server that exposes Ahnlich vector storage and semantic search to MCP-compatible agents.

Ahnlich MCP supports two profiles:

• db connects directly to Ahnlich DB and accepts precomputed embeddings.
• ai sends raw text through Ahnlich AI, which generates embeddings and stores them in Ahnlich DB.

Before you start

Ahnlich MCP connects to running Ahnlich services.

Follow the Ahnlich installation guide to start the required services.

The examples below use the ai profile. To supply your own embeddings, replace --profile ai with --profile db.

Install from PyPI

This is the recommended installation method. Install uv, then use uvx to run Ahnlich MCP directly from PyPI.

Verify that the required Ahnlich services are available:

uvx ahnlich-mcp doctor --profile ai

Claude Desktop

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "ahnlich": {
      "command": "uvx",
      "args": [
        "ahnlich-mcp",
        "--profile",
        "ai"
      ]
    }
  }
}

Restart Claude Desktop after saving the configuration.

If Claude Desktop cannot find uvx, run command -v uvx and use the returned absolute path as command.

Codex

Add the server from your terminal:

codex mcp add ahnlich -- uvx ahnlich-mcp --profile ai

Confirm that it was added:

codex mcp list

You can also use /mcp inside Codex to inspect the connection.

Run with Docker

Use Docker when you want the MCP server and its Python dependencies isolated in a container.

The Ahnlich services must already be running and accessible through their default host ports.

Pull the image:

docker pull ghcr.io/deven96/ahnlich-mcp:latest

Claude Desktop

Add the following to the Claude Desktop configuration:

{
  "mcpServers": {
    "ahnlich": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--add-host",
        "host.docker.internal:host-gateway",
        "-e",
        "AHNLICH_AI_HOST=host.docker.internal",
        "-e",
        "AHNLICH_AI_PORT=1370",
        "ghcr.io/deven96/ahnlich-mcp:latest",
        "--profile",
        "ai"
      ]
    }
  }
}

Restart Claude Desktop after saving the configuration.

Codex

codex mcp add ahnlich -- docker run --rm -i \
  --add-host host.docker.internal:host-gateway \
  -e AHNLICH_AI_HOST=host.docker.internal \
  -e AHNLICH_AI_PORT=1370 \
  ghcr.io/deven96/ahnlich-mcp:latest \
  --profile ai

Install from source

Use this method when developing or contributing to Ahnlich MCP.

Clone the repository and install the locked dependencies:

git clone https://github.com/deven96/ahnlich.git
cd ahnlich/mcp
uv sync --locked --dev

Verify the setup:

uv run ahnlich-mcp doctor --profile ai

The stdio command for MCP clients is:

uv --directory /absolute/path/to/ahnlich/mcp run ahnlich-mcp --profile ai

For Claude Desktop:

{
  "mcpServers": {
    "ahnlich": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ahnlich/mcp",
        "run",
        "ahnlich-mcp",
        "--profile",
        "ai"
      ]
    }
  }
}

For Codex:

codex mcp add ahnlich -- \
  uv --directory /absolute/path/to/ahnlich/mcp \
  run ahnlich-mcp --profile ai

Configuration

Command-line profile selection overrides AHNLICH_PROFILE.

Supported AI models:

• all-minilm-l6-v2
• all-minilm-l12-v2
• bge-base-en-v1.5
• bge-large-en-v1.5
• jina-embeddings-v2-base-code

The selected model must also be enabled in ahnlich-ai through its --supported-models option. The bundled Compose configuration enables all-minilm-l6-v2.

The bundled Compose configuration uses Ahnlich DB 0.3.2 and Ahnlich AI 0.4.1 by default. Override AHNLICH_DB_VERSION or AHNLICH_AI_VERSION only when testing another compatible release.

Example:

AHNLICH_PROFILE=db \
AHNLICH_DB_HOST=127.0.0.1 \
AHNLICH_DB_PORT=1369 \
uv run ahnlich-mcp

Read-only mode

Enable strict read-only mode when the MCP client must not modify Ahnlich:

AHNLICH_MCP_READ_ONLY=1 uv run ahnlich-mcp --profile ai

Only these tools are exposed:

• ping
• server_info
• list_stores
• similarity_search
• get_by_metadata

Mutating tools are omitted from the MCP tool registry.

Tools

Both profiles expose the same tool names by default. Input schemas differ where embeddings are involved.

The db profile requires dimension when creating a store. Its store_entries and similarity_search tools accept embeddings.

The ai profile accepts raw text and uses the configured Ahnlich model to generate embeddings.

Metadata filters use the metadata_filter argument. Filtered metadata keys must have predicate indexes.

Result controls

list_stores and get_by_metadata accept a limit between 1 and 1024. The default is 50.

They return a bounded response:

{
  "results": [],
  "truncated": false
}

similarity_search accepts top_k up to 1024.

Stored embeddings are omitted from DB search and metadata responses by default. Pass include_embeddings: true when the vectors are required.

AI preprocessing

The AI profile supports the following preprocessing modes for store_entries and similarity_search:

The default is none.

Development

Run unit tests:

uv run pytest tests/unit -v

Run integration tests:

docker compose up -d --wait
uv run pytest tests/integration -v

Run the complete test suite:

uv run pytest -v

Run MCP Inspector:

npx -y @modelcontextprotocol/inspector \
  uv \
  --directory "$(pwd)" \
  run ahnlich-mcp \
  --profile ai

License

MIT