Skip to main content
Glama
JVLink MCP Server

JVLink MCP Server

by miyamamoto

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 | 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:

Item

Value

Command

uv

Arguments

run --directory /path/to/jvlink-mcp-server python -m jvlink_mcp_server.server

Environment Variables

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

Protocol

stdio


Database Configuration

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

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

  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

Available Tools

22 tools
check_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.

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

    C2.9/5.0

    Scored across 22 tools

    Disambiguation2/5

    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.

    Naming Consistency3/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language interaction with local SQLite databases through Claude Desktop, translating plain English queries into SQL for data analysis and exploration.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Formula 1 data analysis through natural language, providing tools like track dominance, lap time analysis, and team performance comparisons.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying personal data synced from services like Lunch Money and Strava using SQL via Claude.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to query and manage databases (SQLite, SQL Server, PostgreSQL, MySQL) through natural language, supporting read/write operations and schema management.
      680 npm
      MIT