JVLink MCP Server

You can freely analyze horse racing data just by talking to Claude.

There is no need to write SQL. By asking questions in natural Japanese, you can investigate all kinds of horse racing data, including past race results, jockey performance, and pedigree trends.

You can ask questions like these

"What is the win rate of the 1st favorite?"

"Which jockeys have the most wins this year?"

"Which stallions have the most winning offspring?"

You can also ask questions like these

• Which is more advantageous at Tokyo Turf 1600m, the inner or outer draw?

• Tell me about G1 races where the 1st favorite failed to place.

• What is the performance of Deep Impact's offspring on turf?

• What is the performance of horses weighing 500kg or more?

• Find horses that won with the fastest last 3F time.

Related MCP server: mcp-f1analisys

One-line Installation

With the interactive installer, you can complete everything from cloning to dependency resolution, DB search, and client configuration in one go.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/miyamamoto/jvlink-mcp-server/master/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/miyamamoto/jvlink-mcp-server/master/install.ps1 | iex

💡 If keiba.db is not found, the browser will automatically open the JRA-VAN DataLab subscription page. You can also choose to install jrvltsql at the same time.

Manual Installation

Step 1: Create a Horse Racing Database

Use jrvltsql to fetch data from JRA-VAN and create keiba.db.

A JRA-VAN DataLab subscription is required → https://jra-van.jp/dlb/

If you also need local horse racing data, use NAR (Local Horse Racing) DATA → https://www.keiba-data.com/

Step 2: Clone the Repository

git clone https://github.com/miyamamoto/jvlink-mcp-server.git
cd jvlink-mcp-server
pip install uv
uv sync

Step 3: Configure the MCP Client

Refer to the section below that matches your client.

💡 Dependencies are automatically installed on the first launch (30–60 seconds).

Setup by MCP Client

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "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"
      }
    }
  }
}

For Windows: Change command to "uv.exe". You can also use the .mcpb file from Releases for automatic installation.

Claude Code (CLI)

claude mcp add jvlink \
  -e DB_TYPE=sqlite \
  -e DB_PATH=/path/to/keiba.db \
  -- uv run --directory /path/to/jvlink-mcp-server python -m jvlink_mcp_server.server

If adding to a project scope, append -s project.

Cursor

Create .cursor/mcp.json in the project root:

{
  "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"
      }
    }
  }
}

Confirm that the server is recognized in Cursor Settings → MCP.

VS Code + GitHub Copilot

Create .vscode/mcp.json:

{
  "servers": {
    "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"
      }
    }
  }
}

Enable "chat.mcp.enabled": true in VS Code settings.

Windsurf

Select "Add custom server" from Windsurf Settings → MCP and add to ~/.codeium/windsurf/mcp_config.json:

{
  "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"
      }
    }
  }
}

Codex CLI (OpenAI)

# codex の設定ファイル (~/.codex/config.yaml) に追加するか、
# MCP_SERVERS 環境変数で指定
export MCP_SERVERS='[{"name":"jvlink","transport":{"type":"stdio","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"}}}]'

codex

Other MCP Clients

Common configuration pattern for any client:

Database Configuration

SQLite (Recommended)

DB_TYPE=sqlite
DB_PATH=/path/to/keiba.db

DuckDB

DB_TYPE=duckdb
DB_PATH=/path/to/keiba.duckdb

PostgreSQL

Specify with individual environment variables:

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_NAME=keiba
DB_USER=postgres
DB_PASSWORD=your_password

Or specify with a connection string:

DB_TYPE=postgresql
DB_CONNECTION_STRING=host=localhost;port=5432;database=keiba;username=postgres;password=your_password

Using on Mac / Linux

JRA-VAN data acquisition (jrvltsql) is Windows-only, but this MCP server works if you bring the database to Mac/Linux.

Method 1: Copy the SQLite file — Simply copy keiba.db via Dropbox, Google Drive, etc.

Method 2: Via PostgreSQL — jrvltsql also supports writing to PostgreSQL. You can connect to the Windows PostgreSQL instance from Mac/Linux to use the latest data in real-time.

NAR (Local Horse Racing) Support

Local horse racing data is supported as a standard feature (NAR-compatible tools: nar_favorite_performance, nar_jockey_stats, nar_horse_history). You can analyze data from major local racecourses such as Ohi, Funabashi, Kawasaki, Urawa, Nagoya, and Sonoda.

NV-Link is required to fetch local horse racing data.

Tips for Use

→ To see more example questions, check Sample Questions

Troubleshooting

Server won't start

1. Check if uv is installed: uv --version

2. Check if the path is correct: Does the DB_PATH file exist?

3. Reinstall dependencies: cd /path/to/jvlink-mcp-server && uv sync

Data cannot be retrieved

1. Check if keiba.db was created correctly

2. Check if tables exist: sqlite3 keiba.db ".tables"

3. Check the MCP client logs

PostgreSQL connection error

1. Check if PostgreSQL is running

2. Check if the port is open in the firewall

3. Check the format of DB_CONNECTION_STRING (semicolon-separated)

Regarding the Use of JRA-VAN Data

Data analyzed with this software is provided by JRA-VAN.

Prohibited: Redistribution of data, provision to third parties, sharing of database files

Permitted Use: Personal horse racing analysis/research, internal company use

Please check the JRA-VAN Terms of Service for details.

Changelog

v0.5.0 (2026-04-18)

• Security: Added validation (validate_identifier()) to prevent SQL injection in table and column names

• Security: Improved get_table_schema() in PostgreSQL to use parameterized queries

• Bug fix: Fixed NL_SE filter conditions in sample_data_provider.py (KakuteiJyuni > 0, INTEGER type support)

• Bug fix: Removed duplicate keys in GRADE_CODES in high_level_api.py

• Bug fix: Unified unnecessary type conversions in _horse_history_impl to pd.to_numeric

• Tool rename: MCP tool generate_sql_from_natural_language → get_sql_generation_prompt

• Integrated NAR (local horse racing) support into the master branch (no separate branch needed)

• CI/CD: Added automated tests per PR (ci.yml) and jrvltsql schema sync/auto-release (sync-parent.yml)

License

• Commercial use: Please contact us in advance → oracle.datascientist@gmail.com

• Non-commercial use: Apache License 2.0