JVLink MCP Server
The JVLink MCP Server enables natural language analysis of Japanese horse racing (競馬) data by connecting AI clients (e.g., Claude) to a local horse racing database, without requiring you to write SQL.
Natural Language & SQL
Generate SQL from natural language questions (e.g., "東京芝1600mで1番人気の成績を教えて") via
generate_sql_from_natural_languageExecute arbitrary SELECT queries via
keiba_data_searchValidate SQL for safety before execution
Specialized Analysis — JRA (Central Racing)
favorite_performance: Win/place rates by popularity rank, filterable by venue, grade, distancejockey_stats: Jockey win/place rates and ride countsframe_stats: Inner vs. outer gate advantages by venue/distancehorse_history: Full race history for a specific horsesire_stats: Stallion offspring performance by venue/distance
Specialized Analysis — NAR (Regional Racing)
nar_favorite_performance,nar_jockey_stats,nar_horse_history: Same analyses for regional tracks (Oi, Funabashi, Kawasaki, Urawa, Nagoya, Sonoda, etc.)
Schema & Data Exploration
List tables, get table schemas, preview sample rows, view column examples, and get full database overviews
Query Templates & Examples
Browse and execute pre-built query templates, and access common example queries
Feature Engineering Guidance
Discover important predictive features (past performance, aptitude, jockey, bloodline, etc.) and search them by keyword
Server Management
Check for updates (
check_update) and auto-update the server (update_server)
Database Support: SQLite (recommended), DuckDB, and PostgreSQL — switchable via environment variables.
Provides natural language querying of Japanese horse racing data stored in PostgreSQL databases, enabling real-time analysis of race results, jockey performance, bloodline trends, and historical statistics without writing SQL.
Provides natural language querying of Japanese horse racing data stored in SQLite databases, enabling analysis of race results, jockey performance, bloodline trends, and historical statistics without writing SQL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@JVLink MCP Server 今年の東京芝1600mで1番人気の勝率は?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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?"
Starts | Wins | Win Rate |
6,294 | 2,474 | 39.3% |
"Which jockeys have the most wins this year?"
Jockey | Rides | Wins | Win Rate |
Lemaire | 537 | 142 | 26.4% |
Keita Tosaki | 832 | 135 | 16.2% |
Kohei Matsuyama | 863 | 125 | 14.5% |
Ryusei Sakai | 729 | 119 | 16.3% |
Masami Kawada | 542 | 118 | 21.8% |
"Which stallions have the most winning offspring?"
Stallion | Starts | Wins |
Kizuna | 1,717 | 207 |
Lord Kanaloa | 1,633 | 178 |
Declaration of War | 1,382 | 150 |
Epiphaneia | 1,488 | 138 |
Real Steel | 1,106 | 125 |
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 | bashWindows (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 syncStep 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.jsonWindows:
%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
commandto"uv.exe". You can also use the.mcpbfile 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.serverIf 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"}}}]'
codexOther MCP Clients
Common configuration pattern for any client:
Item | Value |
Command |
|
Arguments |
|
Environment Variables |
|
Protocol | stdio |
Database Configuration
SQLite (Recommended)
DB_TYPE=sqlite
DB_PATH=/path/to/keiba.dbDuckDB
DB_TYPE=duckdb
DB_PATH=/path/to/keiba.duckdbPostgreSQL
Specify with individual environment variables:
DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_NAME=keiba
DB_USER=postgres
DB_PASSWORD=your_passwordOr specify with a connection string:
DB_TYPE=postgresql
DB_CONNECTION_STRING=host=localhost;port=5432;database=keiba;username=postgres;password=your_passwordUsing 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
Tip | Description |
Ask freely | Try asking whatever comes to mind |
Add conditions | Narrow down your analysis with conditions like "in Tokyo," "on turf," or "1600m" |
Request comparisons | It is also good at "Compare A and B" or "Show me the year-over-year trends" |
Dig deeper | If you are curious after seeing an answer, ask follow-up questions. You can deepen your analysis through conversation |
→ To see more example questions, check Sample Questions
Troubleshooting
Server won't start
Check if
uvis installed:uv --versionCheck if the path is correct: Does the
DB_PATHfile exist?Reinstall dependencies:
cd /path/to/jvlink-mcp-server && uv sync
Data cannot be retrieved
Check if
keiba.dbwas created correctlyCheck if tables exist:
sqlite3 keiba.db ".tables"Check the MCP client logs
PostgreSQL connection error
Check if PostgreSQL is running
Check if the port is open in the firewall
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 namesSecurity: Improved
get_table_schema()in PostgreSQL to use parameterized queriesBug 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.pyBug fix: Unified unnecessary type conversions in
_horse_history_impltopd.to_numericTool rename: MCP tool
generate_sql_from_natural_language→get_sql_generation_promptIntegrated 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
Available Tools
22 toolscheck_updateA
サーバーの最新バージョンを確認する。アップデートがあるか確認します。
Inputs: no named parameters.
execute_template_queryC
テンプレートからSQLを生成して実行
Inputs: params (required), template_name (required).
favorite_performanceC
指定した人気順位の馬の成績を分析
1番人気、2番人気など、人気順位別の勝率・複勝率を調べられます。 競馬場やグレード、距離でフィルタリングも可能です。
Inputs: grade, ninki, venue, distance, +1 more.
frame_statsB
枠番(1〜8枠)別の成績を分析
内枠・外枠の有利不利を調べられます。 競馬場や距離でフィルタリングすると、コース特性が見えます。
Inputs: venue, distance, year_from.
get_column_examplesB
特定カラムの値の例を取得(データ形式理解用)
Inputs: table_name (required), column_name (required), limit.
get_database_overviewB
データベース全体の概要を取得
Inputs: no named parameters.
get_database_schemaB
データベーススキーマ情報を取得
Returns:
テーブル一覧、カラム情報、との対応表
Inputs: no named parameters.
get_feature_by_categoryC
カテゴリ別に特徴量を取得
Args:
category: カテゴリ名(過去成績、適性、人的要因、血統など)
Returns:
該当カテゴリの特徴量リスト
Inputs: category (required).
get_important_featuresB
競馬予測で重要な特徴量の知見を提供
Returns:
重要特徴量のリスト、説明、での活用方法
Inputs: no named parameters.
get_query_examplesA
クエリ例集を取得
Returns:
よく使うクエリのサンプル集
Inputs: no named parameters.
get_sql_generation_promptA
自然言語クエリをSQLに変換するためのLLMプロンプトを生成
このツールはSQLを直接実行しません。LLMにSQLを生成させるためのプロンプトを返します。
生成されたSQLは keiba_data_search ツールで実行してください。
Args:
query_text: 自然言語のクエリ
例: "過去3年で東京競馬場の芝1600mで1番人気だった馬の成績を教えて"
例: "ディープインパクト産駒の距離別成績を集計して"
Returns:
LLM用プロンプトとスキーマ情報
Inputs: query_text (required).
get_table_infoB
指定テーブルのスキーマ情報を取得(詳細説明付き)
Args:
table_name: テーブル名
Returns:
カラム情報、テーブル説明、クエリヒントを含む辞書
Inputs: table_name (required).
get_table_sample_dataB
テーブルのサンプルデータを取得(データ形式理解用)
Inputs: table_name (required), num_rows.
horse_historyC
特定の馬の過去レース戦績を取得
馬名を指定して、過去の出走履歴・着順・タイムなどを一覧できます。
Inputs: horse_name (required), year_from.
jockey_statsC
騎手の成績を分析
騎手名を指定して、勝率・複勝率・騎乗数などを調べられます。 競馬場や距離でのフィルタリングも可能です。
Inputs: jockey_name (required), venue, distance, year_from.
keiba_data_searchA
SQLで競馬データを自由に検索・分析できる万能ツール
人気別成績、騎手成績などの専用ツールでカバーできない分析はこのツールで実行できます。
レース結果、オッズ、血統、調教など、あらゆる競馬データにアクセス可能です。
Args:
sql_query: 実行するSQLクエリ(SELECTのみ)
Returns:
クエリ実行結果
Inputs: sql_query (required).
list_query_templatesB
利用可能なクエリテンプレート一覧を取得
Inputs: no named parameters.
list_tablesB
データベース内のテーブル一覧を取得
Returns:
テーブル名のリスト
Inputs: no named parameters. Returns: result
search_featuresB
キーワードで特徴量を検索
Args:
keyword: 検索キーワード(例: "人気", "距離", "騎手")
Returns:
該当する特徴量のリスト
Inputs: keyword (required).
sire_statsB
種牡馬(父馬)の産駒成績を分析
種牡馬名を指定して、産駒の勝率・複勝率を調べられます。 距離や競馬場でフィルタリングすると、血統の適性傾向が見えます。
Inputs: sire_name (required), venue, distance, year_from.
update_serverB
サーバーを更新する。Git checkoutは自動更新し、wheel導入時は手順を返します。
Inputs: no named parameters.
validate_sql_queryC
SQLクエリの安全性を検証
Args:
sql_query: 検証するSQLクエリ
Returns:
検証結果と安全性チェック
Inputs: sql_query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Tools like get_database_schema, list_tables, get_database_overview, and get_table_info all appear to expose overlapping schema/table metadata, and get_query_examples, list_query_templates, and execute_template_query blur the line between examples, templates, and execution. The specialized analytics tools are well-separated, but there is still real ambiguity between arbitrary SQL search and template-driven execution.
Most tool names use snake_case with a get_ or list_ prefix, which is readable and mostly predictable. However, the specialized stats tools are noun-first (jockey_stats, frame_stats, favorite_performance), and keiba_data_search does not follow the verb-first pattern, creating a mixed convention.
At 22 tools, the server is on the heavy side, and several schema/template helpers overlap rather than earning a clearly distinct place. The specialized horse-racing analytics tools justify much of the count, but the maintenance tools and redundant metadata tools could be consolidated.
The server covers schema exploration, SQL validation, query generation/execution, templates, sample data, and common horse-racing analytics, which avoids most dead ends. Dedicated conveniences for race results or odds are missing, but the universal keiba_data_search tool makes the overall surface functionally complete.
Maintenance
Related MCP Connectors
Query, explore, and manage your databases through natural conversation.
Ask questions in plain language, get answers from your business database. No SQL required.
Ask Claude about your Google Ads: campaign performance, wasted search terms, GAQL reports.
Ask business questions in plain English. Get instant answers from your database, no SQL needed.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables natural language interaction with local SQLite databases through Claude Desktop, translating plain English queries into SQL for data analysis and exploration.3MIT
- AlicenseNot gradedqualityDmaintenanceEnables Formula 1 data analysis through natural language, providing tools like track dominance, lap time analysis, and team performance comparisons.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables querying personal data synced from services like Lunch Money and Strava using SQL via Claude.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to query and manage databases (SQLite, SQL Server, PostgreSQL, MySQL) through natural language, supporting read/write operations and schema management.680 npmMIT