Content
# ragflow-knowledge-mcp-server
**Project Overview:**
A simple MCP server of knowledge base for RAGFlow.
This project is a Python-based MCP (Model Context Protocol) server for RAGFlow knowledge bases.
It provides a set of tools to interact with RAGFlow, allowing users to search for knowledge, list available knowledge bases, and retrieve information about specific knowledge bases.
The server is built using the `mcp` library and can be configured to use either `stdio` or `sse` for transport.
The server is configured through a YAML file (`config.yaml`) and environment variables.
**Supported RAGFlow versions:** 0.17.2 ~ 0.19.0
See also [infiniflow/ragflow/blob/main/mcp/server/server.py](https://github.com/infiniflow/ragflow/blob/main/mcp/server/server.py)
## 1. Available tools
### 1. Dynamic knowledge base searching tools
Enable dynamic knowledge base searching tools in `config.yaml`, see also [Server configurations](#3-server-configurations):
```yaml
datasets:
- dataset-id: 00000000000000000000000000000000
search-tool-name: search_xxx_knowledge
#search-tool-description: "Search knowledge about XXX(中文说明)."
#search-tool-result: simple
search-tool-description: "Search knowledge about XXX(中文说明). Results in JSON format, knowledge in the 'content' property."
search-tool-result: json
```
### 2. `list_knowledge_bases` (default disabled)
Enable `list_knowledge_bases` tool in `config.yaml`:
```yaml
list-bases-enabled: true
```
- **Default description:**
List knowledge bases.
- **Input properties:**
* `page`, str: The page number to list the bases for, optional, defaults to 1.
* `limit`, str: The maximum number of knowledge bases to list, optional, defaults to 20.
* `timeout`, int: Dynamic timeout parameter, enabled by `timeout-param-enabled`, optional, defaults to 60 seconds.
### 3. `get_knowledge_base_info` (default disabled)
Enable `get_knowledge_base_info` tool in `config.yaml`:
```yaml
get-base-enabled: true
```
- **Default description:**
Get information of the specified knowledge base ID, results including the knowledge base name, description, and other information.
- **Input properties:**
* `knowledge_base_id`, str: The ID of the knowledge base to query.
* `timeout`, int: Dynamic timeout parameter, enabled by `timeout-param-enabled`, optional, defaults to 60 seconds.
## 2. Install and run
### 2.1. Install using pip
```bash
# Uninstall the previous version
pip uninstall --yes ragflow-knowledge-mcp-server
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
```
### 2.2. Install from source
```bash
cd /path/to/project
pip install .
# Or install using pytools.sh
./pytools.sh reinstall-system
```
### 2.3. Run
```bash
export SIMP_LOGGER_LOG_FILE=/path/to/mcp.log
export SIMP_LOGGER_LOG_LEVEL=DEBUG
# This server can be run directly from the command line:
ragflow-knowledge-mcp-server --config=/path/to/config.yaml
# Alternatively, it can be run as a Python module:
python -m ragflow_knowledge_mcp_server --config=/path/to/config.yaml
# This server can also be run using `uv`:
uv run ragflow-knowledge-mcp-server --config=/path/to/config.yaml
```
### 2.4. Run with Docker or Docker Compose
1. Docker
* Export the `EXTRA_INDEX_URL` environment variable, then run [docker/0.1.0/build.sh](docker/0.1.0/build.sh) to build the image, modifying the build script as needed or building manually.
* Then refer to [docker/0.1.0/run-in-docker.sh](docker/0.1.0/run-in-docker.sh) to run the container.
2. Docker Compose
* Modify the `.env` file.
* Modify the `config.yaml` file.
* Run [docker/0.1.0/docker-compose-up-d.sh](docker/0.1.0/docker-compose-up-d.sh) to start the container, modifying the startup script as needed or running manually.
### 2.4. Testing
```bash
# The project uses `pytest` for testing. To run the tests, first install the test dependencies:
python -m venv .venv
. .venv/bin/activate
uv sync --no-install-project --extra test
# Then run pytest:
pytest
```
## 3. Server configurations
- **YAML**:
Example configurations `yaml`, for full configuration, see [MCPServerProperties.py](src/ragflow_knowledge_mcp_server/properties/MCPServerProperties.py):
```yaml
server-name: ragflow-knowledge-base
default-base-url: http://127.0.0.1:9388/api/v1
default-api-key: ragflow-00000000000000000000000000000000
timeout: 60
timeout-param-enabled: false
# SSE
transport: sse # Defaults to stdio
sse-port: 41106
list-bases-enabled: false
get-base-enabled: false
datasets:
- dataset-id: 00000000000000000000000000000000
search-tool-name: search_xxx_knowledge
search-tool-description: "Search knowledge about XXX(中文说明). Results in JSON format, knowledge in the 'content' property."
- enabled: false
id-param-enabled: true
search-tool-name: search_knowledge
search-tool-description: "Search knowledge from specified knowledge base('knowledge_base_id')."
```
Or configures the base URL and API key for each dataset and tools:
```yaml
server-name: ragflow-knowledge-base
timeout: 60
timeout-param-enabled: false
# SSE
transport: sse # Defaults to stdio
sse-port: 41106
list-bases-enabled: false
list-bases-base-url: http://127.0.0.1:9388/api/v1
list-bases-api-key: ragflow-00000000000000000000000000000000
get-base-enabled: false
datasets:
- dataset-id: 00000000000000000000000000000000
base-url: http://127.0.0.1:9388/api/v1
api-key: ragflow-00000000000000000000000000000000
# Other properties...
```
- **Available environment variables**:
| Yaml | Environment variable name | Default value | Description |
|-----------------------------|----------------------------------------------------------|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| | `RAGFLOW_KNOWLEDGE_MCP_SERVER_CONFIG` | `config.yaml` | The config file path, also available in CLI option `--config=/path/to/config.yaml`. |
| `default-base-url` | `DEFAULT_RAGFLOW_KNOWLEDGE_BASE_URL` | - | The default base URL for the knowledge base. |
| `default-api-key` | `DEFAULT_RAGFLOW_KNOWLEDGE_API_KEY` | - | The default API key for the knowledge base. |
| `server-name` | `RAGFLOW_KNOWLEDGE_MCP_SERVER_NAME` | RAGFlow Knowledge Base | The name of the MCP server. |
| `transport` | `RAGFLOW_KNOWLEDGE_MCP_SERVER_TRANSPORT` | stdio | The transport type. Can be `stdio` or `sse`. |
| `sse-transport-endpoint` | `RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_TRANSPORT_ENDPOINT` | `/messages/` | The SSE transport endpoint. |
| `sse-bind-host` | `RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_BIND_HOST` | 0.0.0.0 | The host to bind the SSE transport. |
| `sse-port` | `RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_PORT` | 41106 | The port for the SSE transport. |
| `sse-debug-enabled` | `RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_DEBUG_ENABLED` | False | Whether to enable debug mode for SSE. |
| `timeout` | `RAGFLOW_KNOWLEDGE_MCP_SERVER_TIMEOUT` | 60 | The timeout for the server. |
| `timeout-param-enabled` | `RAGFLOW_KNOWLEDGE_MCP_SERVER_TIMEOUT_PARAM_ENABLED` | False | Whether to enable the timeout parameter. |
| `timeout-param-description` | `RAGFLOW_KNOWLEDGE_MCP_SERVER_TIMEOUT_PARAM_DESCRIPTION` | `The total timeout for one calling, in seconds, optional, defaults to {self.timeout} seconds.` | The description of the timeout parameter. |
- **Available environment variables of `simp-logger`:**
| Variable name | Default value | Description |
|-------------------------------------|-----------------------------------------------------------|----------------------------------------------------|
| `SIMP_LOGGER_LOG_FILE_ENABLED` | True | Whether to enable logging to file. |
| `SIMP_LOGGER_LOG_CONSOLE_ENABLED` | True | Whether to enable logging to console. |
| `SIMP_LOGGER_LOG_LEVEL` | INFO | The log level. |
| `SIMP_LOGGER_LOG_FILE` | `~/logs/simp-logger.log` | The log file path. |
| `SIMP_LOGGER_LOG_PATTERN` | `%(asctime)s %(levelname)s [%(threadName)s]: %(message)s` | The log pattern. |
| `SIMP_LOGGER_LOG_MAX_BYTES` | 10485760 (10MB) | The maximum size of the log file. |
| `SIMP_LOGGER_LOG_BACKUP_COUNT` | 5 | The number of backup files to keep. |
| `SIMP_LOGGER_LOG_ROTATION_TYPE` | size | The type of log rotation. Can be `size` or `time`. |
| `SIMP_LOGGER_LOG_ROTATION_WHEN` | midnight | The time of day to rotate the log file. |
| `SIMP_LOGGER_LOG_ROTATION_INTERVAL` | 1 | The interval for log rotation. |
| `SIMP_LOGGER_LOG_CLEANUP_DISABLED` | False | Whether to disable logger cleanup. |
## 4. MCP configurations
### 4.1. SSE
Example endpoint: `http://127.0.0.1:41106/sse`
### 4.2. stdio
Simple command line:
```bash
uv run ragflow-knowledge-mcp-server --config=/path/to/config.yaml
```
JSON:
```json
{
"ragflow-knowledge-base": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"ragflow-knowledge-mcp-server",
"--config=/path/to/config.yaml"
],
"env": {
"SIMP_LOGGER_LOG_CONSOLE_ENABLED": false,
"SIMP_LOGGER_LOG_FILE": "/path/to/mcp.log",
"SIMP_LOGGER_LOG_LEVEL": "DEBUG"
}
}
}
```
YAML:
```yaml
ragflow-knowledge-base:
type: stdio
command: uv
args:
- run
- ragflow-knowledge-mcp-server
- "--config=/path/to/config.yaml"
env:
SIMP_LOGGER_LOG_CONSOLE_ENABLED: false
SIMP_LOGGER_LOG_FILE: /path/to/mcp.log
SIMP_LOGGER_LOG_LEVEL: DEBUG
```
## 5. Development Conventions
- The project follows the standard Python packaging conventions.
- The code is organized into modules within the `src/ragflow_knowledge_mcp_server` directory.
- The server logic is in `server.py`, configuration properties are defined in `properties/MCPServerProperties.py`, and the services for interacting with the RAGFlow API are in the `service` directory.
- The project uses `setuptools` for building and `setuptools_scm` for versioning.
- The project uses [`simp-logger`](src/ragflow_knowledge_mcp_server/logger.py) for logging, which can be configured through environment variables.
