ragflow-knowledge

The ragflow-knowledge MCP server provides a lightweight API to interact with RAGFlow knowledge bases. Built with the MCP library in Python, it supports dynamic knowledge-base searching, listing available knowledge bases, and retrieving information about specific knowledge bases. The server can communicate over stdio or Server-Sent Events (SSE) depending on your config, making it easy to plug into various client workflows. Typical usage involves running the server with a YAML configuration file that defines data sources, tools, and transport settings, then querying the exposed MCP tools to search, list, or inspect knowledge bases via the MCP protocol.

Key capabilities include: dynamic knowledge base searching through configured search tools (e.g., search_xxx_knowledge) which return results in JSON format with knowledge content under a specific field; listing knowledge bases (list_knowledge_bases) with pagination parameters; and retrieving metadata about a knowledge base (get_knowledge_base_info) such as name, description, and other attributes. The server is designed to work with RAGFlow versions 0.17.2 to 0.19.0 and is configurable per dataset and tool in config.yaml, including per-base URLs and API keys where needed.

Prerequisites:

• Python 3.8+ installed on your system
• access to install Python packages (pip)
• optionally Docker if you plan to run in containers

Install from PyPI:

# Optional: create a virtual environment
python -m venv .venv
source .venv/bin/activate

# Uninstall any previous version (if needed)
pip uninstall --yes ragflow-knowledge-mcp-server

# Install or upgrade from PyPI
pip install ragflow-knowledge-mcp-server --upgrade --force-reinstall --extra-index-url http://127.0.0.1:8081/repository/pypi-group/simple --trusted-host 127.0.0.1

Install from source:

cd /path/to/project

# Install dependencies and package locally
pip install .

# Optional: reinstall system components using provided script
./pytools.sh reinstall-system

Run the server (examples):

export SIMP_LOGGER_LOG_FILE=/path/to/mcp.log
export SIMP_LOGGER_LOG_LEVEL=DEBUG

# Run via module (recommended for Python)
python -m ragflow_knowledge_mcp_server --config=/path/to/config.yaml

# Or via CLI if installed as a console script
ragflow-knowledge-mcp-server --config=/path/to/config.yaml

# If you prefer SSE/uv, you can run with uv as well (ensure you have uv installed)
uv run ragflow-knowledge-mcp-server --config=/path/to/config.yaml

Docker (optional):

# Build and run according to the project’s docker scripts and instructions in README
# See docker/0.1.0/build.sh and docker/0.1.0/run-in-docker.sh for details

Environment variables:

• RAGFLOW_KNOWLEDGE_MCP_SERVER_CONFIG: Path to the config.yaml file (defaults to config.yaml if not set).
• RAGFLOW_KNOWLEDGE_MCP_SERVER_NAME: Name of the MCP server instance.
• RAGFLOW_KNOWLEDGE_MCP_SERVER_TRANSPORT: transport type (stdio or sse).
• RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_TRANSPORT_ENDPOINT: SSE endpoint path (default /messages/).

Common issues:

• Ensure the config.yaml references correct dataset and tool names, and that any base URLs or API keys are accessible.
• If running with SSE, confirm that the specified sse-port is open and not blocked by a firewall.
• When upgrading, check for breaking changes in the config schema between MCP server versions.
• Validate that Python environment has all dependencies installed (pip install -e . or pip install ragflow-knowledge-mcp-server).