Quick Start Guide

This guide will get you up and running with Grounded Docs in under 5 minutes. You’ll start the server, add documentation, connect your AI assistant, and perform your first search.

Prerequisites

Node.js 22 or later is required. Check your version with node --version.

If you don’t have Node.js 22, you can:

Use nvm: nvm install 22 && nvm use 22
Use Docker (no Node.js required)
Download from nodejs.org

Step 1: Start the Server

Node.js (npx)
Docker
With Embeddings (Recommended)

The fastest way to start. This command downloads and runs the latest version:

npx @arabold/docs-mcp-server@latest

You should see output like:

🚀 Docs MCP Server started
📡 Protocol: http
🌐 Web UI: http://localhost:6280
🔌 MCP endpoint: http://localhost:6280/mcp
📊 SSE endpoint: http://localhost:6280/sse

The server uses port 6280 by default. If this port is in use, specify a different one with --port 6281.

Run in an isolated container with persistent storage:

docker run --rm \
  -v docs-mcp-data:/data \
  -v docs-mcp-config:/config \
  -p 6280:6280 \
  ghcr.io/arabold/docs-mcp-server:latest \
  --protocol http --host 0.0.0.0 --port 6280

The -v flags create persistent volumes so your indexed documentation survives container restarts.

Enable semantic search by providing an OpenAI API key:

OPENAI_API_KEY="sk-proj-your-key-here" npx @arabold/docs-mcp-server@latest

This enables vector search for dramatically better search quality.

You can also use Ollama (local, free), Google Gemini, Azure OpenAI, or AWS Bedrock. See Embedding Models for configuration.

Step 2: Access the Web Interface

Open your browser and navigate to: http://localhost:6280 You’ll see the Grounded Docs web interface where you can:

Add new documentation sources
View indexing progress
Search documentation
Manage your library

Step 3: Add Your First Documentation

Navigate to Add Documentation

Click the “Add Documentation” button on the web interface home page.

Enter Documentation Details

Fill in the form:

Library Name: react (the identifier for this documentation)
Version: 18.x (or leave blank for latest)
URL: https://react.dev/reference/react

Click “Start Scraping”

Watch the Progress

The server will:

Fetch the webpage and discover links
Download all pages within the same domain
Convert HTML to clean markdown
Split content into searchable chunks
Generate embeddings (if configured)

This typically takes 1-3 minutes depending on documentation size.

Verify Completion

When complete, you’ll see the status change to “Completed” with a summary of indexed documents.

The web interface polls for status updates every 3 seconds and displays real-time progress bars.

Step 4: Connect Your AI Assistant

Now configure your AI assistant to use the documentation server:

Claude Desktop
Cursor
VS Code (Cline)
Embedded Mode

Edit your Claude Desktop configuration:macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.jsonAdd this configuration:

{
  "mcpServers": {
    "docs-mcp-server": {
      "type": "sse",
      "url": "http://localhost:6280/sse"
    }
  }
}

Restart Claude Desktop.

Open Settings → Cursor Settings → MCP
Click “Add new MCP server”
Choose “streamableHttp” type
Enter URL: http://localhost:6280/mcp
Save

Or edit your config file directly:

{
  "mcpServers": {
    "docs-mcp-server": {
      "type": "streamableHttp",
      "url": "http://localhost:6280/mcp"
    }
  }
}

Open Cline extension
Click the MCP Servers icon
Choose “Remote Servers”
Add this configuration:

{
  "mcpServers": {
    "docs-mcp-server": {
      "url": "http://localhost:6280/mcp",
      "type": "streamableHttp"
    }
  }
}

Reload the extension.

If you prefer to run the server directly inside your AI assistant without a separate process:

{
  "mcpServers": {
    "docs-mcp-server": {
      "command": "npx",
      "args": ["-y", "@arabold/docs-mcp-server@latest"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-your-key"
      }
    }
  }
}

In embedded mode, you won’t have access to the web interface unless you launch it separately.

For complete client configuration instructions, see Connecting MCP Clients.

Step 5: Test Your Setup

Search via Web Interface

First, verify the documentation is indexed:

Go to http://localhost:6280
Use the search box at the top
Try searching: useState hook
You should see relevant React documentation chunks

Search via CLI

Test from the command line:

npx @arabold/docs-mcp-server@latest search react "useState hook"

Expected output:

🔍 Searching for: "useState hook"
📚 Library: react

📄 Result 1 - React: useState
Source: https://react.dev/reference/react/useState
Relevance: 0.95

Content:
useState is a React Hook that lets you add a state variable to your component.

const [state, setState] = useState(initialState)

Call useState at the top level of your component to declare a state variable...

Query Your AI Assistant

Now ask your connected AI assistant:

How does the useState hook work in React? Please check the documentation.

Your AI will automatically use the search_docs MCP tool to query the indexed documentation and provide grounded, accurate answers.

Next Steps

Now that you’re up and running, explore more features:

Add More Documentation

Index additional libraries:

# Next.js documentation
npx @arabold/docs-mcp-server@latest scrape nextjs https://nextjs.org/docs

# npm package
npx @arabold/docs-mcp-server@latest scrape lodash npm:[email protected]

# Local files
npx @arabold/docs-mcp-server@latest scrape my-project file:///Users/me/projects/my-app

Enable Semantic Search

Configure embeddings for much better search quality:

OpenAI: Best quality (paid)
Ollama: Free, runs locally
Google Gemini: Good alternative

Explore Advanced Usage

Learn about:

Scraping GitHub repositories
Indexing ZIP archives
Managing multiple library versions
Job management and cancellation

Configure Deployment

Production deployment options:

Docker Compose for scaling
Authentication with OAuth2
Telemetry and monitoring

Common CLI Commands

Here are the most useful commands for managing your documentation:

# Show all indexed libraries
npx @arabold/docs-mcp-server@latest list

Troubleshooting

Port 6280 is already in use

Specify a different port:

npx @arabold/docs-mcp-server@latest --port 6281

Update your MCP client configuration to use the new port.

Search returns no results

Possible causes:

Documentation not indexed yet: Check the web interface for job status
Wrong library name: Use npx @arabold/docs-mcp-server@latest list to see indexed libraries
Typo in search query: Try broader terms

Test with a known-good query like searching for the library name itself.

AI assistant not seeing the tools

Verify connection: Check your MCP client logs for connection errors
Restart the client: Most MCP clients need a restart after config changes
Check endpoint: Make sure the URL matches the server’s output
Protocol mismatch: Ensure you’re using the correct endpoint (/mcp for streamableHttp, /sse for SSE)

Scraping fails or hangs

Some websites block automated scraping. Solutions:

Try different URLs: Use the documentation home page or sitemap
Check robots.txt: The site may disallow scraping
Use GitHub instead: Many projects have docs on GitHub that are easier to scrape
Manual download: Download docs locally and use file:// URLs

Database locked errors

This happens when multiple processes try to write simultaneously.Solution: If using embedded mode, launch a separate web UI that connects to the same database:

npx @arabold/docs-mcp-server@latest web --port 6281

Use the web UI for scraping while keeping embedded mode for queries.

Configuration Files

The server auto-creates a configuration file at: macOS/Linux: ~/.config/docs-mcp-server/config.yaml Windows: %APPDATA%\docs-mcp-server\config.yaml You can customize:

Database location
Server ports and host
Embedding model configuration
Search parameters
Scraping limits

See Configuration for full reference.

What’s Next?

You now have a working Grounded Docs setup! Your AI assistant can query accurate, up-to-date documentation instead of relying on potentially outdated training data.

Join the Community

Star the project, report issues, or contribute:

Report bugs and request features
Share your use cases
Contribute code improvements
Help improve documentation

Getting Started

Setup

Guides

Architecture

Infrastructure

Quick Start

Quick Start Guide

Prerequisites

Step 1: Start the Server

Step 2: Access the Web Interface

Step 3: Add Your First Documentation

Step 4: Connect Your AI Assistant

Step 5: Test Your Setup

Search via Web Interface

Search via CLI

Query Your AI Assistant

Next Steps

Add More Documentation

Enable Semantic Search

Explore Advanced Usage

Configure Deployment

Common CLI Commands

Troubleshooting

Configuration Files

What’s Next?

Join the Community

Build docs developers (and LLMs) love

Getting Started

Setup

Guides

Architecture

Infrastructure

​Quick Start Guide

​Prerequisites

​Step 1: Start the Server

​Step 2: Access the Web Interface

​Step 3: Add Your First Documentation

​Step 4: Connect Your AI Assistant

​Step 5: Test Your Setup

​Search via Web Interface

​Search via CLI

​Query Your AI Assistant

​Next Steps

Add More Documentation

Enable Semantic Search

Explore Advanced Usage

Configure Deployment

​Common CLI Commands

​Troubleshooting

​Configuration Files

​What’s Next?

Join the Community

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Step 1: Start the Server

Step 2: Access the Web Interface

Step 3: Add Your First Documentation

Step 4: Connect Your AI Assistant

Step 5: Test Your Setup

Search via Web Interface

Search via CLI

Query Your AI Assistant

Next Steps

Common CLI Commands

Troubleshooting

Configuration Files

What’s Next?