Feyod

You can talk to the Feyod MCP server to ask natural language questions about Feyenoord match data and get precise SQL-backed answers. This MCP server translates your questions into SQL, checks and fixes queries when needed, runs them against a local SQLite database, and returns the results. It supports web-based (HTTP) access and local, script-driven usage through standard MCP client tooling.

How to use

Connect to the public HTTP MCP endpoint to ask questions in natural language and receive structured results. You can also run the MCP server locally via standard command-line invocations and interact with it through MCP-compatible clients.

How to install

Prerequisites: install Python 3.10 or newer and a Python package manager. You will also need an LLM provider API key and compatible provider packages.

Step 1: Set up the project files and dependencies.

# Install Python dependencies using uv (recommended) or pip
# Using uv
uv add "mcp[cli]" langchain langchain-openai langchain-google-genai python-dotenv aiosqlite

# Or using pip
pip install -r requirements.txt

Step 2: Prepare the Feyod database.

# Navigate to the Feyod data directory and build the SQLite database
cd ../feyod
sqlite3 feyod.db < feyod.sql

Step 3: Create an environment file for configuration.

# Path to the SQLite database file (relative to mcp folder or absolute)
DATABASE_PATH="../feyod/feyod.db"

# Server host binding (defaults to localhost/127.0.0.1)
HOST="127.0.0.1"

# Logging level
LOG_LEVEL=INFO

# LLM configuration
LLM_PROVIDER="google"  # or "openai", etc.
LLM_API_KEY="YOUR_API_KEY_HERE"
LLM_MODEL="gemini-2.5-flash"

# Optional example loading configuration
EXAMPLE_SOURCE="local"
EXAMPLE_DB_CONNECTION_STRING=""
EXAMPLE_DB_NAME="feyenoord_data"
EXAMPLE_DB_COLLECTION="examples"

Step 4: Run the MCP server in standard execution mode.

python main.py
# or
mcp run main.py

Configuration

Create a configuration file to specify how the MCP server connects to the database and which LLM provider to use. Use the following example configuration.

# Path to the SQLite database file (relative to mcp folder or absolute)
DATABASE_PATH="../feyod/feyod.db"

# Server host binding (defaults to localhost/127.0.0.1)
HOST="127.0.0.1"

# Logging level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

# LLM Provider configuration
LLM_PROVIDER="google"  # or "openai", etc.
LLM_API_KEY="YOUR_API_KEY_HERE"
LLM_MODEL="gemini-2.5-flash"

# Optional example loading configuration
EXAMPLE_SOURCE="local"  # or "mongodb"
EXAMPLE_DB_CONNECTION_STRING=""
EXAMPLE_DB_NAME="feyenoord_data"
EXAMPLE_DB_COLLECTION="examples"

Security and operational notes

The MCP server runs a read-only database to prevent unintended data modifications. All SQL queries are vetted to ensure only SELECT statements are executed, and the public version mounts the database with read-only permissions.

To control costs and resource use, queries are designed to limit results and your MCP client can enforce pagination or result caps as needed.

Troubleshooting and tips

If you encounter issues, start the server in development mode to enable inspector tooling and verbose logs for debugging.

Verify environment variables and ensure the database file is accessible by the running process. Check that the LLM provider configuration matches the available provider libraries.

Available tools

answer_feyenoord_question

Answers questions about Feyenoord data in natural language, including matches, players, opponents, and related events.