Helix Server

A modern, local-first Model Context Protocol (MCP) server built with Python and managed by uv.

This server is designed to work fully offline (e.g. alongside llama-server running local models like Gemma 2) while providing secure workspace operations, offline searching, and modular web capabilities without requiring paid API keys.

Features

• 🔌 Standard stdio Transport: Connects seamlessly to standard MCP clients like Claude Desktop.
• 🛡️ Secure Filesystem Boundary: All file operations (read, write, delete, list, move) are strictly confined to the workspace root directory.
• 🔎 Offline Search & Indexer: Built-in SQLite FTS5 (Full-Text Search) engine that indices all text and code files in the workspace locally.
• 👁️ File Change Watcher: Background thread utilizing watchdog to monitor workspace additions, deletions, modifications, and moves.
• 🌐 Zero-Cost Web Search: Multi-adapter web search using DuckDuckGo (via Python SDK) and Mojeek (via HTML parsing) with automatic fallback. No API keys required.
• 📄 Clean Web Fetcher: Downloads pages and converts them to readable Markdown, stripping script, style, navigation, and image tags to conserve context window tokens.

Tech Stack

• Python 3.10+
• uv: Blazing-fast dependency resolver & package manager.
• FastMCP: Declarative MCP framework wrapper.
• SQLite FTS5: Fully offline search indexing.
• Watchdog: Multi-threaded file systems events catcher.
• Httpx & BeautifulSoup4: Scraping & page cleanup.

---

MCP Tools Provided

Tool Name	Arguments	Description
web_search	query: str, engine: str = "auto", limit: int = 5	Search the web using DuckDuckGo/Mojeek.
web_fetch	url: str	Downloads a webpage and cleans it to Markdown.
workspace_index	None	Indexes all workspace text/code files locally.
workspace_search	query: str, limit: int = 10	Instantly queries the local index using FTS5 keywords.
file_read	path: str	Reads a text/code file (workspace relative).
file_write	path: str, content: str	Writes content to a file (workspace relative).
file_delete	path: str	Deletes a file or empty directory.
file_move	source: str, destination: str	Moves or renames files or directories.
directory_list	path: str = "."	Lists contents inside a workspace folder.
file_changes_get	None	Returns a log of recent workspace file changes.

---

Getting Started

Prerequisites

Install uv if you haven't already:

• macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
• Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Setup & Installation

Clone this repository and set up dependencies:

git clone https://github.com/b1krams/helix-mcp.git
cd helix-mcp
uv sync

Running Locally

To run the MCP server on stdio transport:

uv run python -m helix_mcp.server

---

Connecting to Clients

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "helix-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/helix-mcp",
        "run",
        "python",
        "-m",
        "helix_mcp.server"
      ]
    }
  }
}

(Make sure to replace /absolute/path/to/helix-mcp with your actual full workspace path).

---

Development & Testing

Run the offline pytest suite to verify all tools:

uv run pytest

Formatting and Linting:

uv run ruff check