jvlink

JVLink MCP Server lets you talk to Claude (or other MCP clients) in natural Japanese to analyze horse racing data without writing SQL. The server serves data from a keiba.db database populated from JRA-VAN sources and supports queries about past race results, jockey performance, bloodline trends, and more. You can ask questions like, “What is the win rate of the #1 horse’s odds in recent G1 races?” or “Which sire lines have produced the most wins this year?” The MCP client configurations shown in the README demonstrate how to connect via UV-based routing so Claude, Cursor, VS Code, Windsurf, and other clients can query the server in real time. To use it, ensure the database is available and the MCP client is configured to launch the server with the appropriate environment variables (DB_TYPE and DB_PATH) so the server can access keiba.db.

Prerequisites:

• Python installed (recommended 3.8+)
• uv (MCP client runner) installed on your system
• Access to a populated keiba.db database (SQLite by default)

Step-by-step:

1. Clone the MCP server repository and navigate into it git clone https://github.com/miyamamoto/jvlink-mcp-server.git cd jvlink-mcp-server

2. Install the uv MCP client runner (Python package) pip install uv

3. Prepare the database (SQLite as recommended) and ensure keiba.db exists

   • Use the provided JR AVL tools or your own process to generate keiba.db
   • Ensure DB_PATH points to the correct location of keiba.db

4. Run or integrate the MCP server with your MCP client

   • Example command (via uv): uv run --directory /path/to/jvlink-mcp-server python -m jvlink_mcp_server.server
   • Or configure your MCP client (Claude Desktop, Cursor, VS Code, etc.) to use the same command and environment variables described in the README.

5. Verify the server is responsive by issuing a sample query from Claude or your MCP client.

Note: The server expects DB_TYPE and DB_PATH environment variables. Adjust DB_PATH to the location of keiba.db and choose DB_TYPE (sqlite/duckdb/postgresql) as needed.

Tips and common considerations:

• Ensure keiba.db exists and is accessible to the MCP runner; verify file permissions.
• If you switch databases (e.g., to Postgres or DuckDB), update DB_TYPE and related connection settings accordingly.
• When using Windows, you may need to adjust the command from uv to uv.exe in your client configuration.
• For local development, keeping the keiba.db file in a synced location (cloud drive) can simplify cross-device usage, but ensure data integrity during concurrent access.
• The server supports multiple MCP clients; the same mcpServers entry can be extended with more server names if needed.
• If the server cannot start, check that uv is installed (uv --version), and that the DB_PATH points to a valid database file.
• The README references several sample client configurations for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and Codex CLI; adapt the environment variables and paths to your local setup.