buun-stack/librechat/README.md

LibreChat

Web-based chat interface for interacting with LLMs:

• Multi-Model Support: Connect to Ollama, OpenAI, Anthropic, and custom endpoints
• MCP Integration: Model Context Protocol for web search and external tools
• Keycloak Authentication: OAuth2/OIDC integration for user management
• Conversation History: MongoDB-backed chat history with search via Meilisearch
• Persistent Storage: User-uploaded images stored persistently

Prerequisites

• Keycloak for OIDC authentication
• Vault for secrets management
• Ollama for local LLM inference (optional)

Installation

just librechat::install

During installation, you will be prompted for:

• LibreChat host: FQDN for LibreChat (e.g., chat.example.com)
• Keycloak host: FQDN for Keycloak (e.g., auth.example.com)
• Tavily MCP: Enable web search via Tavily API (requires API key)

Environment Variables

Variable	Default	Description
LIBRECHAT_NAMESPACE	librechat	Kubernetes namespace
LIBRECHAT_CHART_VERSION	1.9.3	Helm chart version
LIBRECHAT_HOST	(prompt)	LibreChat FQDN
LIBRECHAT_OIDC_CLIENT_ID	librechat	Keycloak client ID
KEYCLOAK_HOST	(prompt)	Keycloak FQDN
KEYCLOAK_REALM	buunstack	Keycloak realm
OLLAMA_HOST	ollama.ollama.svc.cluster.local	Ollama service host
TAVILY_MCP_ENABLED	(prompt)	Enable Tavily MCP (true/false)

Example with Environment Variables

LIBRECHAT_HOST=chat.example.com \
  KEYCLOAK_HOST=auth.example.com \
  TAVILY_MCP_ENABLED=true \
  just librechat::install

Ollama Integration

LibreChat automatically connects to Ollama using the internal Kubernetes service URL. The default models configured are:

• qwen3:8b
• deepseek-r1:8b

LibreChat fetches the available model list from Ollama, so any models you pull will be available.

MCP (Model Context Protocol)

LibreChat supports MCP servers for extending model capabilities with external tools.

Tavily Web Search

When TAVILY_MCP_ENABLED=true, LibreChat can search the web using Tavily API:

1. Get a Tavily API key from tavily.com
2. During installation, enter the API key when prompted (stored in Vault)
3. In the chat interface, select "tavily" from the MCP Servers dropdown
4. The model can now search the web to answer questions

Adding Custom MCP Servers

Edit librechat-config.gomplate.yaml to add additional MCP servers:

mcpServers:
  tavily:
    command: npx
    args:
      - "-y"
      - "tavily-mcp@latest"
    env:
      TAVILY_API_KEY: "${TAVILY_API_KEY}"
  filesystem:
    command: npx
    args:
      - "-y"
      - "@anthropic/mcp-server-filesystem"
      - "/app/data"

Adding API Providers

Edit librechat-config.gomplate.yaml to add OpenAI, Anthropic, or other providers:

endpoints:
  openAI:
    apiKey: "${OPENAI_API_KEY}"
    models:
      default:
        - gpt-4o
        - gpt-4o-mini
      fetch: true

  anthropic:
    apiKey: "${ANTHROPIC_API_KEY}"
    models:
      default:
        - claude-sonnet-4-20250514
        - claude-3-5-haiku-20241022

Store the API keys in Kubernetes secrets and reference them in values.gomplate.yaml.

Operations

Check Status

just librechat::status

View Logs

just librechat::logs

Restart

just librechat::restart

Upgrade

just librechat::upgrade

Uninstall

just librechat::uninstall

This removes the Helm release, namespace, and Keycloak client. Vault secrets are preserved.

To delete Vault secrets:

just vault::delete librechat/credentials

Architecture

LibreChat deployment includes:

• LibreChat: Main application (Node.js)
• MongoDB: Conversation and user data storage
• Meilisearch: Full-text search for conversations

All components run with Pod Security Standards set to restricted.

Troubleshooting

OIDC Login Fails

Symptom: Redirect loop or error after Keycloak login

Check:

1. Verify DOMAIN_CLIENT and DOMAIN_SERVER match your LibreChat URL
2. Check Keycloak client redirect URI matches https://<host>/oauth/openid/callback

just keycloak::get-client buunstack librechat

Ollama Models Not Showing

Symptom: No models available in the model selector

Check:

1. Verify Ollama is running: just ollama::status
2. Check Ollama has models: just ollama::list
3. Check LibreChat logs for connection errors: just librechat::logs

MCP Not Working

Symptom: MCP server not available in dropdown

Check:

1. Verify Tavily secret exists:

   kubectl get secret tavily-api-key -n librechat
   

2. Check for MCP errors in logs:

   just librechat::logs | grep -i mcp
   

3. Verify librechat-config ConfigMap has MCP configuration:

   kubectl get configmap librechat-config -n librechat -o yaml
   

References

• LibreChat Website
• LibreChat Documentation
• LibreChat GitHub
• LibreChat Helm Chart
• Model Context Protocol
• Tavily API