Football Fixture Research MCP Server with Sportmicro API

A focused read-only football fixtures MCP server for AI clients that need grounded fixture research from Sportmicro. The server uses the official @modelcontextprotocol/sdk over stdio and exposes a small set of narrowly scoped tools for date-based fixture lookups, match lookup by ID, and documented match-detail endpoints.

This repository is intentionally limited to endpoints documented in the supplied Sportmicro football OpenAPI reference: https://docs.sportmicro.com/.

Features

• Narrow fixture-research MCP tools

• Date and supported-filter input schemas

• Event detail lookups when documented

• Structured tool responses

• Actionable API error messages

• Read-only operation

Related MCP server: Vublox Agent Tools

What this server can do

Implemented tools:

• search_matches_by_date

• search_matches_by_date_and_league

• get_match_by_id

• get_match_incidents

• get_match_lineups

Each tool validates its inputs before the Sportmicro request is made. Responses are returned as structured JSON text so clients can inspect the result shape or upstream failure details.

Prerequisites

• Node.js 20 or newer

• A Sportmicro API key in SPORTMICRO_API_KEY

Installation

npm install

Environment variables

Copy .env.example to .env and provide your key:

cp .env.example .env

SPORTMICRO_API_KEY=your_api_key_here

Build

npm run build

Test

npm test

Run

After building, start the MCP server with stdio transport:

node dist/index.js

API usage

The server calls only documented Sportmicro football endpoints, including:

• GET /matches-by-date

• GET /matches-by-date-league

• GET /matches

• GET /matches-incidents

• GET /matches-lineups

Example request flow inside the server:

const data = await client.getMatchesByDate('2024-05-01');

The client sends the API key as a Bearer token and maps non-2xx responses to an actionable tool error.

Code example

import { SportmicroClient } from './sportmicro-client.js';

const client = new SportmicroClient(process.env.SPORTMICRO_API_KEY);
const matches = await client.getMatchesByDate('2024-05-01');

Project structure

src/
  index.ts               Entry point export
  server.ts              MCP server and tool registration
  sportmicro-client.ts   Typed Sportmicro HTTP client
  test/                  Node test files

Known limitations

• The server is read-only by design.

• It only exposes a small subset of documented Sportmicro football endpoints.

• Tool responses are structured JSON text rather than custom MCP resources.

• It does not invent fields or endpoints that are not present in the Sportmicro documentation.

License

MIT