Helix MCP Server

Helix MCP 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: ``bash git clone https://github.com/b1krams/helix-mcp.git cd helix-mcp uv sync ``

Running Locally

To run the MCP server on stdio transport: ``bash 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: ``bash uv run pytest ``

Formatting and Linting: ``bash uv run ruff check ``