transfermark-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
transfermark-mcp
Servidor MCP local para consultar datos de Transfermarkt con Bun.
Jugadores · Clubes · Fichajes · Valores de mercado · Clasificaciones · Estadísticas partido a partido
Por qué este servidor
Transfermarkt es la referencia en datos de fútbol, pero no ofrece una API pública. Este servidor envuelve dos fuentes complementarias:
La API JSON oficial que usa la propia web (
tmapi.transfermarkt.technology) — datos estructurados y estables: perfiles, historiales de fichajes, evolución del valor de mercado, estadísticas partido a partido y catálogos de referencia.El HTML renderizado en servidor (
transfermarkt.es) — búsqueda rápida, plantillas, clasificaciones y rankings de valores de mercado.
El resultado es un servidor MCP listo para usar desde opencode, Claude Desktop u otros clientes MCP, con 15 herramientas que cubren el flujo completo: buscar → consultar → comparar.
Related MCP server: PlayerElo MCP server
Tabla de contenidos
Instalación
Requisitos: Bun ≥ 1.3.
git clone <url-del-repo> transfermark-mcp
cd transfermark-mcp
bun installUso rápido
# Servidor MCP por stdio
bun run src/index.ts
# Prueba de humo (cliente MCP real, 23 casos)
bun run test/smoke.ts
# Comprobación de tipos
bun run typecheckHerramientas
Búsqueda
Herramienta | Descripción |
| Busca jugadores por nombre. Devuelve |
| Busca clubes por nombre. Devuelve |
| Busca ligas y torneos. Devuelve |
Jugadores
Herramienta | Descripción |
| Perfil completo: datos personales, posición, contrato, club actual, dorsal y valor de mercado (actual, anterior y máximo). |
| Historial de fichajes: origen, destino, fecha, coste, valor en el momento y contrato. |
| Evolución del valor de mercado por temporada, con club y edad, más el pico histórico. |
| Estadísticas por partido. |
| Partidos y goles con cada selección nacional. |
Clubes
Herramienta | Descripción |
| Liga, ciudad, colores, tamaño de plantilla, edad media y valores de mercado. |
| Plantilla con dorsal, posición, edad, nacionalidad y valor. Admite temporadas históricas. |
| Altas y bajas por temporada con coste de cada operación. |
Competiciones
Herramienta | Descripción |
| Clasificación: posición, partidos, ganados, empatados, perdidos, goles y puntos. |
| Ranking de los jugadores más valiosos de la competición. |
| Temporada actual, país, jornadas y valor de mercado total. |
Referencia
Herramienta | Descripción |
| Catálogos de países, posiciones, lesiones, ausencias, fabricantes y contratos. |
Ejemplos de uso
"¿Quién es el jugador más valioso de LaLiga?"
search_competitions({ query: "LaLiga" }) → competitionId: "ES1"
get_competition_market_values({ competitionId: "ES1", limit: 3 }){
"totalMarketValue": "6.127,10 M€",
"players": [
{ "rank": 1, "name": "Lamine Yamal", "position": "Extremo derecho", "age": "19", "marketValue": "220,00 M€", "club": "FC Barcelona" },
{ "rank": 2, "name": "Kylian Mbappé", "position": "Delantero centro", "age": "27", "marketValue": "200,00 M€", "club": "Real Madrid CF" },
{ "rank": 3, "name": "Jude Bellingham", "position": "Mediocentro ofensivo", "age": "23", "marketValue": "160,00 M€", "club": "Real Madrid CF" }
]
}"¿Cómo ha evolucionado el valor de mercado de Ronaldo?"
search_players({ query: "Cristiano Ronaldo" }) → playerId: 8198
get_player_market_value({ playerId: 8198 })Devuelve 51 puntos de datos (2004 → 2026), con club, edad y valor en cada fecha, además del pico histórico (€120,00 M en 2018) y el valor actual (€10,00 M).
"Estadísticas de goles de un jugador por temporada"
get_player_performance({ playerId: 8198, detail: "summary" }){
"totalGamesInScope": 1663,
"totalPlayed": 1363,
"overall": { "matches": 1363, "minutes": 111309, "goals": 991, "assists": 315, "yellowCards": 168, "redCards": 0 },
"bySeason": [
{ "season": "26/27", "matches": 13, "minutes": 1030, "goals": 9, "assists": 0 },
{ "season": "25/26", "matches": 34, "minutes": 2700, "goals": 25, "assists": 3 }
]
}"Clasificación de la Premier League en 2023"
get_competition_table({ competitionId: "GB1", season: 2023 })Devuelve los 20 equipos con partidos, ganados, empatados, perdidos, goles y puntos.
Configuración
Todo se controla por variables de entorno (con valores por defecto sensatos):
Variable | Por defecto | Descripción |
|
| Dominio a consultar: |
| según dominio | Locale |
| según dominio | Contexto |
|
| TTL por defecto de la caché en memoria. |
|
| Separación mínima entre peticiones al mismo host. |
|
| Peticiones simultáneas por host. |
|
| Timeout de las peticiones HTTP. |
| navegador Chrome | User-Agent enviado a Transfermarkt. |
Ejemplo en inglés:
TRANSFERMARKT_DOMAIN=us bun run src/index.tsIntegración con opencode
Este repositorio ya incluye opencode.json, que registra el servidor como MCP local:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"transfermark": {
"type": "local",
"command": ["bun", "run", "src/index.ts"],
"cwd": ".",
"environment": { "TRANSFERMARKT_DOMAIN": "es" }
}
}
}
}Comprueba el estado de la conexión con:
opencode mcp list
# ✓ transfermark connectedLas herramientas quedan disponibles como transfermark_<herramienta>.
Otros clientes MCP
{
"mcpServers": {
"transfermark": {
"command": "bun",
"args": ["/ruta/absoluta/al/transfermark-mcp/src/index.ts"]
}
}
}Arquitectura
┌──────────────────────────────────────────────────────────────┐
│ Cliente MCP (opencode, Claude Desktop, …) │
└──────────────┬───────────────────────────────────────────────┘
│ stdio (JSON-RPC)
┌──────────────┴───────────────────────────────────────────────┐
│ src/index.ts → src/tools.ts (15 herramientas) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ src/api.ts │ │ src/pages.ts │ │ src/resolver.ts │ │
│ │ API JSON │ │ HTML pages │ │ ids → nombres │ │
│ └──────┬───────┘ └──────┬───────┘ └────────┬────────┘ │
│ └──────────────────┴────────────────────┘ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ src/http.ts (fetch + reintentos + rate limit) │ │
│ │ src/cache.ts (TTL en memoria) │ │
│ │ src/html.ts (parsers cheerio) │ │
│ └───────────────────────────────────────────────────────┘ │
└──────────────┬───────────────────────────────────────────────┘
│ HTTPS
┌──────────────┴───────────────────────────────────────────────┐
│ tmapi.transfermarkt.technology · transfermarkt.es │
└──────────────────────────────────────────────────────────────┘Módulo | Responsabilidad |
| Punto de entrada: servidor MCP sobre stdio. |
| Configuración por variables de entorno. |
| Caché en memoria con TTL y deduplicación de promesas en vuelo. |
|
|
| Cliente de la API JSON de Transfermarkt. |
| Parsers del HTML público (cheerio). |
| Descarga de las páginas solo disponibles en HTML. |
| Resolución de ids a nombres con caché. |
| Registro y handlers de las 15 herramientas MCP. |
| Tipos de las respuestas de la API. |
Desarrollo
bun run typecheck # tsc --noEmit
bun run test/smoke.ts # prueba de humo extremo a extremo (23 casos)
bun run dev # modo watchEl proyecto no tiene dependencias en tiempo de ejecución más allá de @modelcontextprotocol/sdk, cheerio y zod.
Solución de problemas
opencode mcp listno muestra el servidor → asegúrate de estar en el directorio del proyecto; opencode descubreopencode.jsoncaminando los directorios padre.Un parser devuelve datos vacíos → Transfermarkt cambió de maquetación. Todos los selectores están centralizados en
src/html.ts; revisa la página afectada y ajusta el parser. La parte de la API es mucho más estable.La primera llamada a
get_player_performancetarda ~15 s → descarga ~3,6 MB de datos de partido y los cachea 3 h. Las siguientes son instantáneas.Valores de mercado en
nullpara temporadas históricas → la cabecera de la página de plantilla muestra los datos de la temporada actual. La herramienta lo señala con unnoteexplícito en lugar de devolver un dato engañoso.Cambiar de idioma →
TRANSFERMARKT_DOMAIN=de bun run src/index.ts(ous,co.uk, etc.). Las posiciones y ligas se traducen automáticamente.
Licencia
MIT. Los datos son propiedad de Transfermarkt y se accede a ellos respetando su política de uso (limitación de tasa, caché agresiva, User-Agent realista). Este proyecto es un cliente no oficial y no está afiliado a Transfermarkt.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
API-Football MCP — comprehensive soccer/football data
Football-Data.org MCP — soccer competitions, matches, standings
OpenLigaDB MCP — community-run, keyless football / soccer match data. Covers German football…
17 data tools in one MCP server, run on Apify: Google Shopping, Flights, Hotels, News, Images, Videos, Ads Transparency, Jobs and Trends; YouTube transcripts; AI visibility checks; Google Maps leads; App Store and Google Play reviews. Pay per result. Sign in with Apify (OAuth) or an API token.
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides live football data through MCP tools, enabling users to fetch today's matches and top scorers for competitions like the Premier League or World Cup.2-
- AlicenseAqualityCmaintenanceProvides MCP access to PlayerElo's football analytics, including player/coach Elo ratings, match predictions, value bets, and transfer fit scores.171MIT
- FlicenseNot gradedqualityCmaintenanceProvides live football data from API-Football over HTTP, enabling queries for upcoming matches, recent results, current standings, injuries, live matches, and team search through MCP tools.-
- FlicenseNot gradedqualityCmaintenanceEnables querying Liga MX football data, including team form, head-to-head history, and current tournament standings, through MCP tools.-