Sport MCP

Sport MCP is a Rust-based MCP stdio server packaged as an npm CLI. Users can start it with npx, while the actual MCP protocol handling and upstream API calls run in the native Rust binary.

Quick Start

Sport MCP is a stdio MCP server. It should be started by an MCP client. Running npx @sport365/sport-mcp directly in a terminal only starts the stdio server and waits for MCP JSON-RPC messages.

Check the package:

npx -y @sport365/sport-mcp@latest --version
npx -y @sport365/sport-mcp@latest --help

Configure your MCP client like this:

{
  "mcpServers": {
    "sport": {
      "command": "npx",
      "args": ["-y", "@sport365/sport-mcp@latest"],
      "env": {
        "SPORT_AGENT_KEY": "skill_abc123"
      }
    }
  }
}

SPORT_AGENT_KEY is required when calling sport_api_call. It is sent to the upstream API as X-Agent-Key. The server can still start without it, and sport_list_domains remains available for checking supported domains.

For Claude Desktop, add the same JSON object under mcpServers in the Claude Desktop config file, then restart Claude Desktop. For Cursor or other MCP clients, use the same command, args, and env fields in that client's MCP server configuration UI.

Optional environment variables:

| Variable | Default | Description | | --- | --- | --- | | SPORT_API_BASE_URL | https://beta-skill-api.zhitiyu.com/ | Override the upstream API host. | | SPORT_API_TIMEOUT_SECS | 20 | HTTP timeout in seconds. | | X_AGENT_KEY | none | Fallback when SPORT_AGENT_KEY is not set. |

The default upstream URL is compiled into the Rust binary from crates/sport-core/build.rs. The API documentation entry is https://beta-skill-api.zhitiyu.com/docs/api.

Troubleshooting

If the MCP client reports the server as unavailable:

• Confirm the command is npx, not node.
• Confirm args are ["-y", "@sport365/sport-mcp@latest"].
• Confirm SPORT_AGENT_KEY is configured in the MCP client env when calling sport_api_call.
• Restart the MCP client after editing its config.
• Run npx -y @sport365/sport-mcp@latest --help to print the expected config.
• Run npm view @sport365/sport-mcp version to confirm npm can see the package.

If sport_list_domains works but sport_api_call returns a missing key error, the server is installed correctly and only the SPORT_AGENT_KEY env value is missing or not visible to the MCP client process.

MCP Tools

The server exposes two MCP tools:

| Tool | Description | | --- | --- | | sport_list_domains | List supported football and basketball API domains. | | sport_api_call | Call a whitelisted Skill API domain with query parameters. |

Example sport_api_call input:

{
  "ball_type": "ft",
  "kind": "data",
  "domain": "match-info",
  "query": {
    "matchId": "123456"
  }
}

For material APIs, repeated query parameters can be passed as arrays:

{
  "ball_type": "bk",
  "kind": "material",
  "domain": "match",
  "query": {
    "matchId": "123456",
    "materialIndexList": ["1", "3"]
  }
}

API references:

• Football API
• Basketball API

Project Structure

bin/sport-mcp.js             npm/npx wrapper
crates/sport-core            Core config, domain registry, HTTP client
crates/sport-mcp-server      Rust MCP stdio server binary
docs/architecture.md         Chinese architecture design
docs/api/                    Skill API documents
scripts/                     Build, staging and packaging scripts
dist/                        Generated build and npm package output

Node only selects and starts the native binary. It does not parse MCP messages or call upstream APIs. The Rust server writes MCP JSON-RPC messages through stdio and writes normal logs to stderr.

Build

Build the current platform:

npm run build

Build Windows x64 and Linux x64:

npm run build:win-linux

Build all supported native binaries:

npm run build:all

build:all currently stages:

native/sport-mcp-server-win32-x64.exe
native/sport-mcp-server-linux-x64
native/sport-mcp-server-darwin-x64
native/sport-mcp-server-darwin-arm64

On Windows, Linux x64 is built with Docker by default when Docker is available. macOS cross builds use cargo-zigbuild, Zig and a configured macOS SDK.

macOS Cross Build On Windows

Required tools:

choco install zig -y
cargo install --locked cargo-zigbuild
rustup target add x86_64-apple-darwin aarch64-apple-darwin

Configure the macOS SDK:

$env:SDKROOT="D:\sdks\MacOSX.sdk"
$env:MACOSX_SDK_PATH="D:\sdks\MacOSX.sdk"

Then build:

npm run build:mac:zig

Package

Generate an npm tarball for the current platform:

npm run package

Generate a full-platform tarball:

npm run package:all

The output is written to:

dist/artifacts/

The npm staging directory is:

dist/npm/

Publish

The package name is already configured as:

{
  "name": "@sport365/sport-mcp"
}

Build the full-platform package first:

npm login
npm run package:all

Then publish the staged package:

npm publish ./dist/npm --access public

If the npm account uses WebAuthn, passkey, security key, Chrome, or Windows Hello for 2FA, do not pass --otp. The npm CLI will print a browser verification URL. Open it in Chrome, complete Windows Hello or security key verification, then paste the returned token back into the terminal.

Architecture

The detailed architecture design is written in Chinese:

• Architecture Design