Docs MCP

🚀 docs-mcp

An MCP server that enables users to efficiently search and reference user-configured documents.

🚀 Quick Start

Prerequisites

To use docs-mcp, you need uv, a fast tool for Python package and project management.

Installing uv

curl -LsSf https://astral.sh/uv/install.sh | sh

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

brew install uv

pip install uv

🚀 The Simplest Usage

You can use it immediately in a project with existing documents:

# Create a folder for document management
mkdir -p my-docs/docs
# Place document files in docs/

Add the following to the Claude Desktop configuration (claude_desktop_config.json):

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

Important: docs-mcp always refers to the docs/ directory in the project folder.

✨ Features

• 📄 Document Listing - List all documents and their descriptions.
• 🔍 grep Search - Perform fast full-text searches using regular expressions.
• 🧠 Semantic Search - Conduct semantic similarity searches using OpenAI Embeddings (configuration required).
• 📝 Document Retrieval - Retrieve the full content of a specified document.
• 📖 Pagination Support - Efficiently browse large documents page by page.

📦 Installation

Method 1: Using with Existing Documents

You can immediately make your local Markdown or text files searchable:

1. Create a project folder.
2. Place documents in the docs/ directory.
3. Update the Claude Desktop configuration.

✅ Advantages: No command-line operations required, ready to use immediately.
❌ Disadvantages: Import tools cannot be used.

Method 2: Utilizing Import Tools

When importing documents from GitHub or websites:

# Set up a document management project
uv init my-docs
cd my-docs
uv add docs-mcp

# Import documents from GitHub
uv run docs-mcp-import-github https://github.com/owner/repo

# Import only a specific directory
uv run docs-mcp-import-github https://github.com/owner/repo/tree/main/docs -o project-docs

✅ Advantages: Easily import external documents.
❌ Disadvantages: uv setup is required.

💻 Usage Examples

Enabling Semantic Search

You can add semantic search using OpenAI Embeddings:

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

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

Add the API key to the Claude Desktop configuration:

{
  "mcpServers": {
    "docs": {
      "command": "uvx",
      "args": ["docs-mcp"],
      "env": {
        "DOCS_BASE_DIR": "/path/to/my-docs",
        "OPENAI_API_KEY": "sk-..."  // Semantic search is enabled
      }
    }
  }
}

Detailed Configuration Options

{
  "mcpServers": {
    "docs": {
      "command": "uvx",
      "args": ["docs-mcp"],
      "env": {
        "DOCS_BASE_DIR": "/path/to/my-docs",
        "OPENAI_API_KEY": "sk-...",
        "DOCS_FOLDERS": "api,guides,examples",  // Only load specific folders
        "DOCS_FILE_EXTENSIONS": ".md,.mdx,.txt,.py",  // Limit target file extensions
        "DOCS_MAX_CHARS_PER_PAGE": "5000",  // Maximum characters per page
        "DOCS_LARGE_FILE_THRESHOLD": "10000"  // Automatic pagination threshold (number of characters)
      }
    }
  }
}

Available Tools

MCP Tools (for use within Claude)

• list_docs - List documents.
• get_doc - Retrieve document content (supports pagination).
• grep_docs - Perform regular expression searches.
• semantic_search - Conduct semantic similarity searches (OpenAI API key required).

📖 Using the Pagination Feature

For large documents (over 15,000 characters), the first page is automatically displayed, and pagination is recommended:

# Basic usage (as before)
get_doc("path/to/document.md")  # Small files are displayed in full, large files automatically show the first page

# Using pagination
get_doc("path/to/document.md", page=1)  # First page (default up to 10,000 characters)
get_doc("path/to/document.md", page=2)  # Second page
get_doc("path/to/document.md", page=3)  # Third page

Example of pagination output:

📄 Document: pytest/reference/plugin_list.rst
📖 Page 2/5 (chars 10,001-20,000/45,123)
📏 Lines 285-570/1,324 | Max chars per page: 10,000
⚠️  Large document auto-paginated. To see other pages:
💡 get_doc('pytest/reference/plugin_list.rst', page=3)  # Next page
💡 get_doc('pytest/reference/plugin_list.rst', page=5)  # Last page
────────────────────────────────────────────────────────────

[Document content]

Command-line Tools (for document management)

• docs-mcp-import-url - Import documents from websites.
• docs-mcp-import-github - Import from GitHub repositories.
• docs-mcp-generate-metadata - Generate metadata for semantic search.

📚 Documentation

Required Environment

• uv - A Python environment and package management tool (executed with the uvx command).
• Python 3.12 or higher (automatically managed by uv).
• OpenAI API key (only required when using semantic search).

Detailed Configuration

Environment Variables

Supported File Formats

Example Directory Structure

my-docs/
└── docs/
    ├── api/
    │   └── reference.md
    ├── guides/
    │   └── quickstart.md
    └── examples/
        └── sample.py

Information for Developers

Development from Source

git clone https://github.com/herring101/docs-mcp.git
cd docs-mcp
uv sync

# Testing
uv run pytest tests/

# Building
uv build

Details of Command-line Tools

docs-mcp-import-url https://example.com/docs --output-dir imported

# Import the entire repository
docs-mcp-import-github https://github.com/owner/repo

# Import only a specific path (saved in docs/imported)
docs-mcp-import-github https://github.com/owner/repo/tree/main/docs --output-dir imported

# Automatically detect repositories on the master branch
docs-mcp-import-github https://github.com/Cysharp/UniTask

export OPENAI_API_KEY="your-key"
docs-mcp-generate-metadata

Security

• API keys are managed through environment variables.
• Access is restricted using DOCS_FOLDERS and DOCS_FILE_EXTENSIONS.
• External network access is limited to the OpenAI API.

Troubleshooting

📄 License

MIT License - LICENSE

Contribution

Refer to CONTRIBUTING.md.