Marcus Local

You run a local MCP server that indexes documentation sites and your code repositories to let AI assistants search them semantically. It creates embeddings, stores them in a vector store, and serves search results through the MCP protocol so your AI tools can quickly retrieve relevant docs and code chunks from your environment.

How to use

You connect an MCP client (such as Cursor or Claude Desktop) to the Marcus Local MCP Server to perform searches across indexed docs and repositories. Start by indexing your sources, then query from your AI assistant to retrieve precise, chunked results. Use the web UI to manage sources and run searches, or send commands from your MCP-enabled assistant to search all sources or a specific source.

Usage patterns you will rely on:

• Add documentation sources and repositories via the Web UI to index content you want searchable.
• Run indexing tasks to convert pages and files into 800-token chunks, embed them with OpenAI embeddings, and store them in the vector database.
• Ask your AI assistant to search with queries like “show me the authentication flow in the docs” or “find all occurrences of a function in my repo,” and filter results by source when needed.

From your MCP-enabled assistant you can issue searches that target all sources or a specific source. If you want more focused results, filter by the source name (Docs or Repos) to limit the returned chunks to that source.

How to install

Follow these concrete steps to install and run the Marcus Local MCP Server with its web UI.

# 1) Clone the project and navigate to the workspace
git clone <your-repo>
c d <workspace-directory>

# 2) Install Node.js dependencies for the Web UI
npm install

# 3) Set up a Python virtual environment for the MCP server
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# Windows: venv\Scripts\activate

# 4) Install Python dependencies for the MCP server
pip install -r mcp-docs-server/requirements.txt

# 5) Install Crawl4AI tooling used by the crawler and indexer
pip install -U crawl4ai
crawl4ai-setup

Configure the server

Create a .env file under the mcp-docs-server directory and set your API key and embedding model preferences.

OPENAI_API_KEY=your_openai_api_key_here
EMBEDDING_MODEL=text-embedding-3-small
DEFAULT_RESULTS=5

Run the Web UI

Launch the web interface to manage sources and view indexing progress.

# Start Next.js server
npm run dev

# Open the web UI in your browser
open http://localhost:3030

Connect your MCP client

Configure your MCP client to connect to the local MCP server using the stdio configuration shown here. These examples illustrate the exact commands you would run from your client to start the MCP server for dialogue with your AI assistant.

{
  "mcpServers": {
    "marcus_docs": {
      "type": "stdio",
      "command": "/path/to/your/venv/bin/python3",
      "args": ["/path/to/crawl4ai_test/mcp-docs-server/server/main.py"]
    },
    "claude_docs": {
      "type": "stdio",
      "command": "/path/to/your/venv/bin/python",
      "args": ["/path/to/crawl4ai_test/mcp-docs-server/server/main.py"]
    }
  }
}

Available tools

crawler

Crawls documentation sites and collects pages for indexing using Crawl4AI.

indexer

Indexes crawled docs or repository files by chunking content and generating embeddings.

repo_indexer

Indexes local code repositories excluding common ignore directories.

search

Performs search over indexed chunks and returns relevant results to the MCP client.

delete_source

Removes a source from the index and clears associated chunks.