Fess MCP Server is a middleware server that integrates with the Fess search engine. By registering it in the settings of MCP clients such as Claude for Desktop, it enables agents to obtain information using Fess. Fess is an open-source full-text search server provided under the Apache License. Commercial support is also available. For more details, please refer to the official website. https://fess.codelibs.org/ja/

For the setup procedure 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

Start the server with the following command:

docker-compose up -d

Here we show the setup procedure using uv. uv is a fast Python package manager. While not required, we recommend using it.

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

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

# Install dependencies
uv pip install -e .

# Start MCP server
uv run .\fess_mcp_server.py

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

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

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

Here we show the testing procedure 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 Fess server):
uv run pytest -v tests/integration/ -s

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

# Build 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 Fess server):
docker run --rm --network host fess-mcp-server-test pytest -v tests/integration/ -s

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

• -v: Show verbose output
• -s: Show standard output
• --cov: Generate coverage report
• --cov-report=html: Generate HTML coverage report

MIT License