Fess MCP Server

🚀 Fess MCP Server

Fess MCP Server is a middleware server integrated with the Fess search engine. By registering it in the settings of an MCP client (such as Desktop Claude), it allows the proxy to use Fess to retrieve information. Fess is an open - source full - text search server provided under the Apache License. Commercial support is also available. For more detailed information, please visit the official website. https://fess.codelibs.org/ja/

🚀 Quick Start

Fess MCP Server serves as a bridge between MCP clients and the Fess search engine. It enables clients to access Fess's information retrieval capabilities.

📦 Installation

Fess Installation

For the installation steps of the Fess server itself, please refer to the official Fess documentation. https://qiita.com/g_fukurowl/items/a00dbbad737d3e775108

The following article may also be helpful: https://qiita.com/g_fukurowl/items/a00dbbad737d3e775108

Fess MCP Server Installation

Using Docker

Use the following command to start the server:

docker-compose up -d

Without Docker

Here are the installation steps using uv. uv is a fast Python package manager. Although it is not required, it is recommended.

# Install uv
irm https://astral.sh/uv/install.ps1 | iex

# Activate the virtual environment
.\.venv\Scripts\activate.bat

# Install dependencies
uv pip install -e .

# Start the MCP server
uv run .\fess_mcp_server.py

Configuration

Fess Server Connection Settings

The URL of the Fess server accessed by Fess MCP Server is set as the environment variable Fess_API_BASE. Please modify this variable according to your environment before starting Fess MCP Server. If it is running in a Docker container, edit docker - compose.yaml and change the relevant settings.

Desktop Claude Connection Settings

Fess MCP Server runs on port 8000 by default. If Fess MCP Server is running on port 8000 of localhost, edit claude_desktop_config.json as follows:

{
  "mcpServers": {
    "fess-search-sse": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "http://localhost:8000/sse"
        ]
      }
  }
}

💻 Usage Examples

Testing

Without Docker

Here are the testing steps using uv.

# Install development dependencies:
uv pip install -e ".[test]"

# Run unit tests:
uv run pytest -v tests/unit/ -s

# Run integration tests (requires communication with the Fess server):
uv run pytest -v tests/integration/ -s

# Generate a coverage report:
uv run pytest --cov=fess_mcp_server --cov-report=html

Running Tests in a Docker Container

# Build the test Docker image:
docker build -t fess-mcp-server-test -f Dockerfile.test .

# Run unit tests:
docker run --rm fess-mcp-server-test pytest -v tests/unit/ -s

# Run integration tests (requires communication with the Fess server):
docker run --rm --network host fess-mcp-server-test pytest -v tests/integration/ -s

# Generate a coverage report:
docker run --rm -v ${PWD}/coverage:/app/coverage fess-mcp-server-test pytest --cov=fess_mcp_server --cov-report=html

Test Execution Options

• -v: Display detailed output
• -s: Display standard output
• --cov: Generate a coverage report
• --cov-report=html: Generate a coverage report in HTML format

📄 License

MIT License