How do I use rag-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@rag-mcp what are the treatment options for autonomic dysreflexia?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

`$ rag-mcp`

MCP server for Fathom Works RAG — exposes the self-hosted knowledge base as tools any MCP-capable LLM can call.

Query documents, manage libraries, and ingest local files or URLs without opening the web UI.

`[ what it does ]`

Tool	Who can call it	Description
`query`	any user	Semantic + BM25 search across one or more libraries; returns LLM answer with citations
`list_libraries`	any user	List libraries and their document counts
`list_documents`	any user	List documents, optionally filtered by library or title
`add_file`	admin	Ingest a local file (PDF, TXT, DOC, DOCX) into a library
`add_url`	admin	Ingest a web URL into a library
`get_job_status`	admin	Check ingestion job progress
`delete_document`	admin	Remove a document and all its vectors

Related MCP server: Hoard

`[ quick start ]`

Option A — run with Python (no Docker)

git clone https://github.com/Jemplayer82/rag-mcp.git
cd rag-mcp
pip install -r requirements.txt
cp .env.example .env   # fill in RAG_BASE_URL + credentials
python mcp_server.py   # starts the stdio MCP server

Option B — run with Docker

docker pull ghcr.io/jemplayer82/rag-mcp:latest

No config file needed — pass environment variables directly at runtime (see Claude config below).

`[ connect to Claude ]`

Claude Desktop (`claude_desktop_config.json`)

Docker (recommended — zero local setup):

{
  "mcpServers": {
    "rag": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "RAG_BASE_URL=http://YOUR_RAG_HOST:8000",
        "-e", "RAG_USERNAME=admin",
        "-e", "RAG_PASSWORD=yourpassword",
        "ghcr.io/jemplayer82/rag-mcp:latest"
      ]
    }
  }
}

Python (local install):

{
  "mcpServers": {
    "rag": {
      "command": "python",
      "args": ["/path/to/rag-mcp/mcp_server.py"],
      "env": {
        "RAG_BASE_URL": "http://YOUR_RAG_HOST:8000",
        "RAG_USERNAME": "admin",
        "RAG_PASSWORD": "yourpassword"
      }
    }
  }
}

Claude Code (`.claude/mcp.json`)

{
  "mcpServers": {
    "rag": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "RAG_BASE_URL=http://YOUR_RAG_HOST:8000",
        "-e", "RAG_USERNAME=admin",
        "-e", "RAG_PASSWORD=yourpassword",
        "ghcr.io/jemplayer82/rag-mcp:latest"
      ]
    }
  }
}

Or via CLI:

claude mcp add rag -- docker run -i --rm \
  -e RAG_BASE_URL=http://YOUR_RAG_HOST:8000 \
  -e RAG_USERNAME=admin \
  -e RAG_PASSWORD=yourpassword \
  ghcr.io/jemplayer82/rag-mcp:latest

`[ auth ]`

Method	Variables	Notes
Username + password	`RAG_USERNAME`, `RAG_PASSWORD`	Recommended. Token is fetched on first call and refreshed automatically on expiry.
Static JWT	`RAG_TOKEN`	Works but cannot self-refresh. Copy from browser DevTools → Application → Local Storage → `rag_token`.

`[ environment variables ]`

Variable	Default	Description
`RAG_BASE_URL`	`http://localhost:8000`	Base URL of the RAG app (no trailing slash)
`RAG_USERNAME`	—	Admin or user account username
`RAG_PASSWORD`	—	Account password
`RAG_TOKEN`	—	Pre-generated JWT (alternative to username/password)

`[ using the tools ]`

Ask a question (search all libraries):

query("What are the treatment options for autonomic dysreflexia?")

Narrow to specific libraries:

query("Jones Act seaman status elements", library_ids=[2, 5])

Ingest a local file:

add_file("/Users/me/docs/protocol.pdf", library_id=1, title="Care Protocol 2024")
get_job_status(42)  # poll until complete

Ingest a URL:

add_url("https://example.com/article", title="Article", library_id=1)

`[ smoke test ]`

Test without connecting to Claude Desktop using the MCP Inspector:

RAG_BASE_URL=http://YOUR_HOST:8000 RAG_USERNAME=admin RAG_PASSWORD=yourpass \
  npx @modelcontextprotocol/inspector python mcp_server.py

`[ requirements ]`

Python 3.10+ (uses X | None type annotations) — local machine, not the RAG container
Running Fathom Works RAG instance (self-hosted or VPS)

`[ license ]`

Released under the GNU AGPL-3.0.

Part of the Fathom Works RAG ecosystem.

This server cannot be installed

F

license - not found

-

quality - not tested

C

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

rag-mcp

`$ rag-mcp`

`[ what it does ]`

`[ quick start ]`

Option A — run with Python (no Docker)

Option B — run with Docker

`[ connect to Claude ]`

Claude Desktop (`claude_desktop_config.json`)

Claude Code (`.claude/mcp.json`)

`[ auth ]`

`[ environment variables ]`

`[ using the tools ]`

`[ smoke test ]`

`[ requirements ]`

`[ license ]`

Maintenance

Resources

Latest Blog Posts

MCP directory API

$ rag-mcp

[ what it does ]

[ quick start ]

Option A — run with Python (no Docker)

Option B — run with Docker

[ connect to Claude ]

Claude Desktop (claude_desktop_config.json)

Claude Code (.claude/mcp.json)

[ auth ]

[ environment variables ]

[ using the tools ]

[ smoke test ]

[ requirements ]

[ license ]

Maintenance

Resources

Latest Blog Posts

MCP directory API

`$ rag-mcp`

`[ what it does ]`

`[ quick start ]`

`[ connect to Claude ]`

Claude Desktop (`claude_desktop_config.json`)

Claude Code (`.claude/mcp.json`)

`[ auth ]`

`[ environment variables ]`

`[ using the tools ]`

`[ smoke test ]`

`[ requirements ]`

`[ license ]`