JVLink

You set up and run an MCP server that lets you interrogate horse racing data via natural language. No SQL is required—you ask in plain Japanese or English, and the server analyzes past race results, jockey performance, bloodline trends, and more to deliver insights and comparisons.

How to use

You interact with the MCP client by asking questions as if you are having a conversation with a knowledgeable data assistant. Start with simple questions and gradually add conditions to refine results. For example, ask about race winners by jockey, or compare two horses on specific metrics. The system can handle questions like “Which jockey had the most wins this year?” or “How do progeny of a given sire perform on turf at 1600m?” You can also request trend analyses over time, or request comparisons across different races, tracks, or surfaces.

Practical usage tips:

• Add conditions to filter results, such as location, surface, or distance (e.g., “Tokyo turf 1600m inner vs outer gate”).
• Request comparisons between entities (e.g., “Compare Horse A and Horse B by win rate and recent form”).
• Drill down based on results you receive (e.g., if you see a surprising trend, ask for deeper breakdowns by race class or jockey).
• Explore different data themes, including track bias, speed figures, or progeny performance by sire.

How to install

Prerequisites: you need Python installed, and a running MCP runner (uv) to host the MCP server. You will also need to obtain or prepare the local database file (keiba.db) containing the JRA data.

Step 1: Install the MCP runner and set up the server configuration.

Step 2: Create or obtain the keiba.db database file containing data from JRA-VAN.

Step 3: Run the MCP server with the appropriate environment variables to point to your database.

Configuration and environment

{
  "mcpServers": {
    "jvlink": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/jvlink-mcp-server", "python", "-m", "jvlink_mcp_server.server"],
      "env": {
        "DB_TYPE": "sqlite",
        "DB_PATH": "/path/to/keiba.db"
      }
    }
  }
}

{
  "mcpServers": {
    "jvlink": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/jvlink-mcp-server", "python", "-m", "jvlink_mcp_server.server"],
      "env": {
        "DB_TYPE": "postgresql",
        "DB_HOST": "your-windows-pc.local",
        "DB_PORT": "5432",
        "DB_NAME": "keiba",
        "DB_USER": "your_user",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Notes:

• The first snippet configures SQLite with a local keiba.db file.
• The second snippet shows how to switch to PostgreSQL for real-time updates. Adjust /path/to/jvlink-mcp-server to your actual MCP server path and keiba.db to your database file as needed.

## Security and data usage

Use the server to analyze data locally or in your secured network. Do not expose sensitive data to external parties. The data sources come from JRA-VAN under their terms, so ensure you comply with data usage policies and license terms.

## Troubleshooting and notes

If the server does not start, verify that the keiba.db path is correct and that the uv runner is installed. Check that environment variables DB\_TYPE and DB\_PATH (or DB\_HOST, DB\_PORT, DB\_NAME, DB\_USER, DB\_PASSWORD for PostgreSQL) are set correctly. Ensure network access to any remote database if you are using PostgreSQL.

## Available tools

### Query horse data

Retrieve and analyze race results, jockey stats, and progeny performance using natural language questions.

### Compare riders

Ask for head-to-head comparisons of riders by metrics like win rate, mounts, and recent form.

### Analyze progeny by sire

Evaluate offspring success by sire line, including race types and surfaces.

### Trend analysis

Request trends over time for metrics such as winning percentages and performance by track.