WindTools

WindTools MCP Server enables semantic code search and document embedding for code assistance by indexing code files, storing embeddings in ChromaDB, and providing fast retrieval through a modular MCP interface. It is designed to work asynchronously, start quickly, and be configurable via environment variables so you can tailor it to your codebase and runtime environment.

How to use

You interact with WindTools MCP Server through an MCP client to search code snippets, browse a codebase, and initialize indexing. You can index your code from specified directories and then run queries that return relevant code snippets based on semantic similarity. Use the provided tools to explore directories, check initialization progress, index repositories, and perform codebase searches. Start the server, ensure the background initialization completes, and then execute searches to retrieve snippets that match your query.

How to install

Prerequisites: Python 3.11, and a working MCP client or environment that can run MCP servers.

Install from PyPI and set up the environment by installing the WindTools MCP package.

Install the package via pip:

How to install

pip install windtools-mcp

How to install

Optionally install from source to develop locally.

How to install

git clone https://github.com/ZahidGalea/windtools-mcp
cd windtools-mcp
pip install -e .

How to install

Configure runtime for MCP with environment variables and a runtime command. You will typically set DATA_ROOT, CHROMA_DB_FOLDER_NAME, and SENTENCE_TRANSFORMER_PATH to suit your environment.

How to install

{
  "mcpServers": {
    "windtools": {
      "command": "uv",
      "args": [
        "run",
        "windtools-mcp"
      ],
      "env": {
        "DATA_ROOT": "/Users/<user>/windtools_data",
        "CHROMA_DB_FOLDER_NAME": "chromadb",
        "SENTENCE_TRANSFORMER_PATH": "jinaai/jina-embeddings-v2-base-code"
      }
    }
  }
}

How to install

If you are integrating with Claude Desktop, you can place the following configuration in your Claude setup to run WindTools MCP Server directly.

How to install

{
  "mcpServers": {
    "windtools": {
      "command": "uvx",
      "args": [
        "-p",
        "3.11",
        "-U",
        "windtools-mcp"
      ],
      "env": {
        "DATA_ROOT": "/Users/<user>/windtools_data",
        "CHROMA_DB_FOLDER_NAME": "chromadb",
        "SENTENCE_TRANSFORMER_PATH": "jinaai/jina-embeddings-v2-base-code"
      }
    }
  }
}

Additional setup and usage notes

The server loads the ChromaDB index and embedding model in the background to minimize startup time. You can check initialization progress using the provided initialization status tool and start querying once initialization completes.

Development notes

Development requires Python 3.11 and dependencies listed in pyproject.toml. Install development dependencies with uv sync --dev and, if you want to run from source, install in editable mode.

Tools available

WindTools MCP Server exposes several tools to interact with codebases and embeddings. These are available endpoints you can call through the MCP client.

Available tools

list_dir

List the contents of a directory. Inputs: directory_path (absolute path). Returns JSON with file types and sizes.

get_initialization_status

Check the status of the background initialization process. Returns JSON with initialization status for ChromaDB and the embedding model.

index_repository

Index code files from specified directories into ChromaDB. Inputs: target_directories (array of absolute paths), force_reindex (optional boolean). Returns JSON with indexing statistics.

codebase_search

Find code snippets relevant to a search query. Inputs: query, limit (optional), min_relevance (optional). Returns JSON with matching code snippets.