jvdata-bridge-mcp

AIエージェントに競馬データベース（PostgreSQL）への直接アクセスを提供するMCP（Model Context Protocol）サーバーです。

⚠️ 本サーバーの利用には、JVData Bridge で構築された PostgreSQL データベースが必要です。

💡 概要

jvdata-bridge-mcp をMCPクライアント（AIエージェント）に接続することで、競馬データの検索・分析や予想ナレッジの参照が可能になります。

• 標準 50 ツール (canonical tools): レース・出馬表・オッズ・血統・調教・予測指標などの検索

• 予想ナレッジ (MCP Resources): resources/list, resources/read と knowledge_list, knowledge_read で判断知識を参照

• カスタム SQL 実行: Read-only トランザクション＆安全フィルタ付きの分析機能

提供データ領域

発走前の独立評価には race_forecast_context(race_code) で出馬表・過去走・相手・調教・位置・コース・血統と 現在の観測をまとめて取得できます。取得範囲は対象レースと現在時刻から自動で決まり、 対象自身・未来・部分速報を除外します。過去時点の予想再現には対応しません。 今日の候補は search_races(race_date="today", upcoming_only=True) で発走予定とともに検索できます。 馬評価を固定した後、odds_table(race_code, bet_type="trio", combinations=["3-6-7"]) で買い目を照会できます。 馬・騎手・調教師・コースの個別集計にも race_code を渡すと取得範囲が自動で決まります。 全ツールの参照面と入出力はツールリファレンス、検証方針はアーキテクチャを参照してください。 入力・出力・取得の順序は発走前予想コンテキストを参照してください。

Related MCP server: mcp-postgres

🚀 クイックスタート

1. 前提条件

• Python 3.11+（uv 推奨）

• JVData Bridge で構築した PostgreSQL データベース

2. セットアップ

git clone https://github.com/GracefulTabby/jvdata-bridge-mcp.git
cd jvdata-bridge-mcp
uv sync

予測モデルはパッケージに同梱しています。 線形モデルの勝率・複合分析には、対象の出馬表と全候補馬の jv_mart.horse_speed_quality が必要です。 ペース・位置は速度表示の欠測だけでは停止しません。必要なDBデータはデータベース契約、 モデルの適用域・較正状態・配布はモデル開発を参照してください。

.env.example をコピーして .env を作成し、DB接続情報を指定します。

JVDATA_BRIDGE_MCP_DATABASE_URL=postgresql+psycopg://user:password@127.0.0.1:5432/jvdata

Dockerで起動する場合は、DB接続用の .env を用意して docker compose up --build -d を実行します。 MCP接続先は http://127.0.0.1:8080/mcp です。ホスト上のDBには host.docker.internal を使います。 HTTP・プロキシ設定はトランスポートを参照してください。

3. 動作確認

uv run jvdata-bridge-mcp doctor

※ JSON出力の "ok": true および DB接続・ツール数が正常であることを確認してください。

🔌 MCPクライアント設定

お使いのMCPクライアントに合わせて設定を追加してください（cwd は実際のプロジェクトパスに置換）。

stdio モード (推奨)

JSON形式 (Claude Desktop / Cursor / VS Code / Claude Code など):

{
  "mcpServers": {
    "jvdata-bridge-mcp": {
      "command": "uv",
      "args": ["run", "jvdata-bridge-mcp", "stdio"],
      "cwd": "/path/to/jvdata-bridge-mcp"
    }
  }
}

TOML形式 (OpenAI Codex など):

[mcp_servers."jvdata-bridge-mcp"]
command = "uv"
args = ["run", "jvdata-bridge-mcp", "stdio"]
cwd = "/path/to/jvdata-bridge-mcp"
startup_timeout_sec = 30
tool_timeout_sec = 60

Streamable HTTP モード (ネットワーク経由・ChatGPT等)

uv run jvdata-bridge-mcp serve --transport streamable-http --host 127.0.0.1 --port 8765

• MCP Endpoint: http://127.0.0.1:8765/mcp

• Health check: http://127.0.0.1:8765/health

🛠️ カスタムSQL分析

標準ツールでカバーできない複雑な集計は、AIエージェントが sql_get_table_schema でテーブル定義を確認のうえ、sql_execute_custom_query でクエリを実行できます。

• 安全設計: トランザクションは Read-only で固定されており、sqlglot 解析により単一の SELECT/WITH 文のみを許可します（書き込み・スキーマ変更・危険な関数の呼び出しは自動拒否）。

📚 ドキュメント & ライセンス

予測モデルの仕様と学習・評価手順は 予測モデルの開発・配布 を参照してください。

• 詳細仕様: アーキテクチャ | 設定 | DB仕様 | ツール一覧 | トランスポート | 発走前予想コンテキスト

• ライセンス: Apache License 2.0 (Copyright 2026 Ryuya Matsumoto)

• ※ 競馬データ、JV-Link、外部モデル等の権利はそれぞれの提供元に帰属します。