outlook-rag

# outlook-rag

Semantic and keyword search for Outlook email through MCP. Index your mail locally and search it using an OpenAI-compatible embedding API.

Features

• Semantic search combined with Japanese keyword search (BM25 + vector search).

• All-date indexing of connected mail folders, including open archive PSTs.

• Incremental updates, reusable embedding caches, and bounded batches.

• Support for Qwen and other OpenAI-compatible embedding models.

• Local storage with read-only access to Outlook.

Related MCP server: Outlook MCP Server

Requirements

• Windows and Outlook Classic with a configured mail profile.

• uv on your PATH.

• An embedding API and its model name and API key.

Python 3.11-3.13 is supported. The example uses Python 3.12; uv can download it on the first run.

Installation

Add the following to your OpenCode configuration. Replace the model and API key with your own values.

{
  "mcp": {
    "servers": {
      "outlook_rag": {
        "type": "local",
        "command": [
          "uvx", "--python", "3.12", "--from",
          "git+https://github.com/camucamulemon7/outlook-rag.git@v0.5.0",
          "outlook-rag"
        ],
        "environment": {
          "OUTLOOK_RAG_MODEL": "Qwen/Qwen3-Embedding-8B",
          "OUTLOOK_RAG_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

uvx installs the server and its dependencies on first connection. No clone or separate application configuration file is required. Reload OpenCode to connect; use an absolute path to uvx if it is not on your PATH.

The default embedding endpoint is http://localhost:8080/api/v1/embeddings. Add OUTLOOK_RAG_EMBEDDING_URL to environment for another endpoint.

For offline startup, replace @v0.5.0 with the full commit SHA shown on GitHub, run that command online once, then add --offline after uvx. Keep the Python version and uv caches available. Your embedding API must still be running.

Usage

1. Call sync_emails to index mail. Each call processes up to 200 changed emails by default; repeat until folder windows are complete and no folders remain pending.

2. Call search_emails with a natural-language query, then get_indexed_mail to read a result.

3. Call sync_emails again when you want to include new or changed mail. Sync does not run automatically.

For a smaller sync, pass {"max_total_emails": 10}. After bulk indexing, call optimize_index to build the vector search index.

Configuration

Only the model and API credentials are required. Other settings have defaults:

Changing the embedding model requires re-indexing. With the default database location, a separate index is selected automatically. If you set OUTLOOK_RAG_DATA_DIR, use a new directory for the new model.

See Configuration for optional settings and opencode.example.json for a ready-to-edit configuration.

Limitations and data handling

The server does not modify Outlook mail. Email text and vectors are stored locally; cleaned text and queries are sent to your configured embedding API.

Only indexed mail is searchable. Attachments, New Outlook, and disconnected PST files are not supported. Deleted or moved mail is removed from the local index by sync_emails with reconcile=true after a complete scan.

Development

git clone https://github.com/camucamulemon7/outlook-rag.git
cd outlook-rag
uv run --frozen python -m unittest discover -s tests -p test_offline.py -v

License

MIT. Dependencies and embedding models have their own licenses.