home / mcp / docs mcp server

Docs MCP Server

Provides fast document search, retrieval, and semantic search with paginated access for user documents.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "herring101-docs-mcp": {
      "command": "uvx",
      "args": [
        "docs-mcp"
      ],
      "env": {
        "DOCS_FOLDERS": "api,guides,examples",
        "DOCS_BASE_DIR": "REQUIRED: path to your docs root",
        "OPENAI_API_KEY": "sk-...",
        "DOCS_FILE_EXTENSIONS": ".md,.mdx,.txt",
        "DOCS_MAX_CHARS_PER_PAGE": "10000",
        "DOCS_LARGE_FILE_THRESHOLD": "15000"
      }
    }
  }
}

You can search, browse, and retrieve your own documents efficiently with a dedicated MCP server. It enables fast full-text queries, semantic search, and paginated viewing so you can quickly find the exact sections and details you need.

How to use

You interact with the server through an MCP client to list documents, search, and fetch content. Use the provided MCP configurations to connect your client to the local or remote server, then run searches or open documents as needed.

How to install

Prerequisites you need before running the MCP server are Python and a tool to manage Python packages. Install the management tool for your OS, then install the runtime package.

# Install the runtime manager for your OS
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" 

# macOS using Homebrew
brew install uv

# Python package install (alternative)
pip install uv

Connecting via an MCP client with a local stdio server

To run a local MCP server that you connect to from Claude Desktop, use a standard local runtime command. The following example shows running the server through the runtime tool with the working directory containing your documents.

{
  "mcpServers": {
    "docs": {
      "type": "stdio",
      "name": "docs",
      "command": "uvx",
      "args": ["docs-mcp"],
      "env": {
        "DOCS_BASE_DIR": "/path/to/my-docs"
      }
    }
  }
}

Enable semantic search (optional)

If you want semantic search, supply an OpenAI API key and generate metadata for your documents. This enhances search results by understanding meaning, not just exact terms.

# 1. Set your OpenAI API key
export OPENAI_API_KEY="sk-..."

# 2. Generate semantic metadata (run in the project root)
uv run docs-mcp-generate-metadata

Configuration notes

You can customize what you load and how results are paged using environment variables within your MCP config. For example, you can limit to specific folders, restrict file types, and adjust how many characters appear per page.

{
  "mcpServers": {
    "docs": {
      "type": "stdio",
      "name": "docs",
      "command": "uvx",
      "args": ["docs-mcp"],
      "env": {
        "DOCS_BASE_DIR": "/path/to/my-docs",
        "OPENAI_API_KEY": "sk-...",
        "DOCS_FOLDERS": "api,guides,examples",
        "DOCS_FILE_EXTENSIONS": ".md,.mdx,.txt,.py",
        "DOCS_MAX_CHARS_PER_PAGE": "5000",
        "DOCS_LARGE_FILE_THRESHOLD": "10000"
      }
    }
  }
}

Available tools

list_docs

List all documents with their descriptions

get_doc

Retrieve the full content of a specified document with pagination support

grep_docs

Perform regex-based searches across documents

semantic_search

Run semantic search using OpenAI embeddings (requires API key)

docs-mcp-import-url

Import documents from a website URL

docs-mcp-import-github

Import documents from a GitHub repository

docs-mcp-generate-metadata

Generate metadata for semantic search