DevDocs MCP Server

A Model Context Protocol (MCP) stdio process that enables AI assistants like Claude to access your local DevDocs instance via HTTP, providing seamless search and retrieval of technical documentation for hundreds of programming languages, frameworks, and tools.

Quick Start

# Install via Homebrew
brew tap emaland/devdocs-mcp
brew install devdocs-mcp

# Start DevDocs
devdocs-mcp-start

# Configure Claude
claude mcp add --env DEVDOCS_URL=http://localhost:9292 devdocs /usr/local/bin/devdocs-mcp

# Restart Claude and start using!

Architecture: This is not an HTTP server - it's a stdio-based process that communicates with Claude using the MCP protocol. The MCP server connects to a separately running DevDocs instance (typically on http://localhost:9292) to fetch documentation.

Example use (Claude)

search svelte docs for how to manage state and describe to me what it says

⏺ I'll search the Svelte documentation for information about state management and describe what it says.

⏺ devdocs - search_docs (MCP)(slug: "svelte", query: "state management") ⎿ No matches found for 'state management' in svelte documentation

⏺ devdocs - search_docs (MCP)(slug: "svelte", query: "state") ⎿ Search results for 'state' in svelte:

 • $state [Runes] - path: `$state`
 … +1 line (ctrl+r to expand)

⏺ devdocs - get_doc_content (MCP)(slug: "svelte", path: "$state", format: "text") ⎿ $state On this page $state $state.raw $state.snapshot Passing state into functions Passing state across modules The $state rune allows you to create reactive st ate, which means that your UI reacts when it changes. <script> let count = $state(0); </script> <button onclick={() => count++}> clicks: {count} </button> Unlik e other frameworks you may have encountered, there is no API for interacting with state — count is just a number, rather than an object or a function, and you c … +46 lines (ctrl+r to expand)

⏺ Based on the Svelte documentation, here's what it says about state management:

Svelte State Management with $state Rune

[...]

Prerequisites

1. DevDocs running locally on port 9292 (see options below)
2. Pandoc for high-quality HTML to Markdown conversion:

   brew install pandoc
   

DevDocs Installation Options

Option 1: Quick Start with Pre-built Image (Multi-GB Download)

docker run --name devdocs -d -p 9292:9292 ghcr.io/freecodecamp/devdocs:latest

Note: This pulls the official DevDocs image which includes ALL documentation sets (multiple gigabytes).

Option 2: Build Custom Image with Selected Docs (via Homebrew)

If you installed via Homebrew, you can build a custom DevDocs image with only the docs you need:

# List available documentation sets
devdocs-mcp-build --list

# Build with specific docs only
devdocs-mcp-build svelte tailwindcss react

# Or use preset collections
devdocs-mcp-build --minimal     # Just essential docs
devdocs-mcp-build --popular     # Common documentation
devdocs-mcp-build --frontend    # Frontend-focused

This approach creates a much smaller image with only the documentation sets you need.

Option 3: Build Minimal DevDocs Manually

For a smaller, faster setup with only the documentation you need:

1. Clone the DevDocs repository:

   git clone https://github.com/freeCodeCamp/devdocs.git
   cd devdocs
   

2. Modify the DevDocs Dockerfile to include only specific docs:

   # Edit the DevDocs Dockerfile and change this line:
   - RUN thor docs:download --all && \
   + RUN thor docs:download svelte tailwindcss vite && \
   

   You can specify any documentation sets you need. Popular options include:

   • react vue angular svelte (frontend frameworks)
   • python javascript typescript go rust (languages)
   • django rails express fastapi (backend frameworks)
   • postgresql mongodb redis (databases)
   • docker kubernetes terraform (DevOps)

   Run thor docs:list in the DevDocs directory to see all available options.

3. Build the custom image:

   # For most systems:
   docker buildx build -t devdocs:latest --load .
   

4. Run your custom DevDocs:

   docker run --name devdocs -d -p 9292:9292 devdocs:latest
   

Installation

Using Homebrew (Recommended)

# Install the MCP server
brew tap emaland/devdocs-mcp
brew install devdocs-mcp

# Configure Claude
claude mcp add --env DEVDOCS_URL=http://localhost:9292 devdocs /usr/local/bin/devdocs-mcp

# Test the connection (optional)
devdocs-mcp-cli list

From Source

1. Install uv:

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

2. Clone and set up the project:

   git clone https://github.com/emaland/devdocs-mcp.git
   cd devdocs-mcp
   uv sync
   

3. Ensure DevDocs is running (see Prerequisites above)

4. Add MCP server to Claude:

   claude mcp add --env DEVDOCS_URL=http://localhost:9292 devdocs /path/to/devdocs-mcp/devdocs_mcp_server.py
   

Available Commands (Homebrew Installation)

After installing via Homebrew, you get these commands:

Command	Purpose
devdocs-mcp	MCP server (called automatically by Claude)
devdocs-mcp-cli	CLI tool to test and explore DevDocs
devdocs-mcp-start	Start DevDocs Docker container
devdocs-mcp-stop	Stop DevDocs Docker container
devdocs-mcp-build	Build custom DevDocs with selected docs

Using Docker Compose

Run DevDocs in Docker (the MCP server runs as a stdio process through Claude):

docker-compose up -d

Note: This starts DevDocs in a container. The MCP server itself runs as a subprocess of Claude, not in Docker.

CLI Tool

A command-line interface is provided for testing and exploring the MCP endpoints:

# If installed via Homebrew
devdocs-mcp-cli list
devdocs-mcp-cli search svelte component
devdocs-mcp-cli interactive

# Or if running from source
uv run python scripts/cli.py list

# Search in a specific documentation set
uv run python scripts/cli.py search svelte component
uv run python scripts/cli.py search tailwindcss color

# Get content from a documentation page
uv run python scripts/cli.py get svelte introduction
uv run python scripts/cli.py get tailwindcss installation

# Interactive mode for exploration
uv run python scripts/cli.py interactive

# Use different output formats
uv run python scripts/cli.py list --format json
uv run python scripts/cli.py get svelte introduction --format html

# Connect to a different DevDocs instance
uv run python scripts/cli.py --url http://localhost:3000 list

Interactive Mode

The interactive mode provides a REPL-like interface:

devdocs> list                    # List all documentation sets
devdocs> slugs                   # Show just the slugs for easy copying
devdocs> search svelte state     # Search for 'state' in Svelte docs
devdocs> get svelte introduction # Get content from a page
devdocs> help                    # Show available commands
devdocs> quit                    # Exit

Development

Install development dependencies:

uv sync --group dev

Run tests:

# Run all pytest tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run integration tests only
uv run python tests/test_integration.py

# Run all tests including linting
uv run python scripts/test.py

Code formatting:

uv run black .
uv run ruff check .

Available Tools

list_docs

Lists all available documentation sets in the DevDocs instance.

Example output:

• Svelte (v5.33.11) - slug: `svelte`
• Tailwind CSS (v4.1.11) - slug: `tailwindcss`
• React - slug: `react`

search_docs

Search for entries within a specific documentation set.

Parameters:

• slug: Documentation set identifier (e.g., "svelte", "tailwindcss")
• query: Search term to find matching entries

Example:

search_docs(slug="svelte", query="component")

get_doc_content

Retrieve the full content of a specific documentation page.

Parameters:

• slug: Documentation set identifier
• path: Path to the documentation page
• format: Return format ("text" or "html", defaults to "text")

Example:

get_doc_content(slug="svelte", path="introduction", format="text")

Usage with Claude Desktop

Quick Setup

1. Ensure DevDocs is running (see Prerequisites section above for options)

2. Configure Claude Desktop:

   Using Claude CLI (recommended):

   # If running from source:
   claude mcp add --env DEVDOCS_URL=http://localhost:9292 devdocs /path/to/mcp/devdocs_mcp_server.py
   
   # If installed via Homebrew:
   claude mcp add --env DEVDOCS_URL=http://localhost:9292 devdocs /usr/local/bin/devdocs-mcp
   

   Or manually edit Claude's config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "devdocs": {
         "command": "uv",
         "args": ["run", "python", "devdocs_mcp_server.py"],
         "cwd": "/path/to/devdocs/mcp",
         "env": {
           "DEVDOCS_URL": "http://localhost:9292"
         }
       }
     }
   }
   

3. Restart Claude Desktop to load the MCP server.

See CLAUDE_SETUP.md for detailed setup instructions and troubleshooting.

Environment Variables

• DEVDOCS_URL: URL of the DevDocs instance (default: http://localhost:9292)

Quick Start

# Quick setup with automatic configuration
./scripts/quick-setup.sh

# Or use the install script for more options
./scripts/install.sh

Scripts

All scripts are located in the scripts/ directory:

• scripts/quick-setup.sh - Quick setup with uv and Docker
• scripts/install.sh - Installation wizard with multiple options
• scripts/build-devdocs.sh - Build custom DevDocs with selected documentation
• scripts/cli.py - Interactive CLI for testing MCP endpoints
• scripts/test.py - Run all tests including linting
• scripts/dev.py - Development helper scripts
• scripts/update-homebrew-sha.sh - Update SHA256 hashes for Homebrew formula
• scripts/run_mcp_server.sh - Run the MCP server with Docker

The devdocs CLI wrapper remains for convenient access to the CLI:

• ./devdocs list - List available documentation
• ./devdocs search svelte component - Search documentation
• ./devdocs interactive - Interactive mode

Building Custom DevDocs

Instead of downloading the full multi-GB DevDocs image, you can build a custom image with only the documentation you need:

# Build with specific docs
./scripts/build-devdocs.sh svelte tailwindcss react

# Build with popular documentation sets
./scripts/build-devdocs.sh --popular

# Build with frontend-focused docs
./scripts/build-devdocs.sh --frontend

# List all available documentation sets
./scripts/build-devdocs.sh --list

# Build for specific platform
./scripts/build-devdocs.sh --platform linux/arm64 python django

After building, the script will:

1. Create a custom Docker image (e.g., devdocs:custom)
2. Optionally update docker-compose.yml to use your custom image
3. Allow you to use devdocs-mcp-start and devdocs-mcp-stop with your custom build

This is especially useful for:

• Reducing disk space (custom builds are much smaller)
• Faster startup times
• Including only relevant documentation for your projects