Soccerverse MCP

The Soccerverse MCP server lets an AI assistant, or your own code, look up live game data with ready-made tools: clubs, players, users, markets, fixtures, transfers, votes, shop data and leaderboards. It is read-only and needs no API key. The server address is:

https://mcp.soccerverse.com/mcp

The tools return the same data as the hosted APIs on play.soccerverse.com, which the Overview describes.

#Connect an AI client

Use these settings in any MCP client that supports Streamable HTTP servers:

• URL: https://mcp.soccerverse.com/mcp
• Transport: Streamable HTTP
• Authentication: none. There is no API key, token or special header, and the server is read-only.

In Claude Code, add it with:

claude mcp add --transport http soccerverse https://mcp.soccerverse.com/mcp

The server accepts MCP protocol versions 2024-11-05, 2025-03-26 and 2025-06-18. The Mcp-Session-Id that initialize returns is optional, so you can also call tools/list and tools/call directly, as in the next section.

GET https://mcp.soccerverse.com/health returns {"status":"healthy","data_loaded":true} and works as a health check.

Use /mcp. The older /sse path does not work with standard MCP clients.

#Try it with curl

tools/list returns every tool with its input schema and is the authoritative list. tools/call runs one tool. No handshake is needed.

# List every tool
curl -sS https://mcp.soccerverse.com/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call one tool: the details of club 50
curl -sS https://mcp.soccerverse.com/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_club_details",
      "arguments": {"club_id": 50}
    }
  }'

The reply is a JSON-RPC envelope. The tool's result is a JSON string in result.content[0].text, so parse it a second time. A shortened example (the real text has many more fields):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"club_id\":50,\"balance\":\"37989431.56 SVC\",\"form\":\"WWWLDD\"}"
      }
    ]
  }
}

#Limits and errors

• Rate limit: about 5 requests per second, with bursts of up to about 30. Over the limit you get HTTP 429, a Retry-After: 1 header and {"error":"Rate limit exceeded"}. Wait a second and try again. These numbers are measured, not promised, and may change.
• Batches: one POST /mcp can carry up to 20 JSON-RPC messages in an array. More gets HTTP 413.
• Browsers: the server sends no CORS headers, so JavaScript on another website cannot call it. Use an MCP client, or call it from your own server.
• A bad call can fail in two ways, so check for both:
  • A normal result whose text is {"error":"...","success":false}. isError is not set, so look for success: false. Examples: an unknown tool, get_fixture without fixture_id, and get_club_details for a club that does not exist.
  • A JSON-RPC error with code -32603 and message Tool execution error. The details are in data. Examples: 404: No job posting found for club ID 50, 400: At least one of country_id, comp_id, or club_id must be provided, and 422: ... for a value the API behind the tool rejects.
• Some bad calls give no error at all. Required parameters are not always enforced: get_squad without club_id returns 50 unrelated players, and an id that does not exist can return an empty list or null. A few parameters that tools/list shows are ignored, and the tables below mark the ones we know about. Always send every parameter a tool needs, and check that the reply is about what you asked for.
• If a script gets 403 error code: 1010, send a normal User-Agent header. Python's default urllib one is blocked. curl is not.

#Money values

Raw REST and GSP money values are integers in units of 1/10,000 SVC. Divide by 10,000: a raw 123456789 is 12,345.6789 SVC.

MCP tools convert most money values for you. Read each one like this:

1. Already in SVC. Use the _svc field when there is one, such as price_svc. Text that ends in SVC, such as "37989431.56 SVC", is also already converted. Do not divide either. A _short field such as "38.0M SVC" is shortened for display and loses digits, so do not calculate with it. For example, get_share_orders_dump gives one order's price as 157600, its price_svc as 15.76 and its price_short as "15 SVC": use price_svc.
2. Raw, so divide by 10,000. The fields listed below have no converted twin.
3. Plain numbers that are already in SVC. The money totals in get_market_data, the values in get_player_payouts and svc_per_influence_per_season in get_club_earnings_light. Do not divide them.

The raw fields for step 2:

• get_share_balances_detailed: club_balance, player_value, total_spent, sale_proceeds, remaining_cost_basis, realised_pl, earnings_7d, earnings_30d and the payout fields such as lifetime_payouts, season_payouts and last_week_payouts. The wages and last_price fields in the same rows are already converted.
• get_club_balance_sheet_weeks: dilution_income. The other columns are already converted.
• get_player_details, search_players and get_squad: volume_1_day, volume_7_day, last_7days and last_7days_price.
• get_trading_graph: volume and weighted_average_price.

Shop prices and referral spend (USDC) are scaled by 1,000,000 instead of 10,000. Text such as "$47" comes with a _raw field (usd_spent_raw, price_per_pack_raw) that holds the raw amount, so 47000000 is $47. get_referrals_leaderboard_all has only a raw usd_spent: divide it by 1,000,000. Plain numbers with usdc in the name, such as total_earnings_usdc, are already dollars.

Money filters that you send do not all use the same unit. These take raw units (SVC multiplied by 10,000): min_bid and max_bid on get_transfer_market, min_wage and max_wage on search_players, and wages_min and wages_max on get_player_details. The min_balance and max_balance filters on search_clubs take plain SVC.

#Notes

• Country ids are 3-letter codes such as ENG, ESP and DEU, never numeric codes.
• The Datacentre REST API numbers divisions from 0 (0 is the top division). MCP tools use 1 for the top division.
• MCP replies often add names (club_name, player_name, league_name) and readable dates next to ids and unix timestamps.
• Fixture timestamps usually use date (unix seconds), not timestamp.
• Always set share_type on get_share_balances (club, player or all). On get_share_balances_detailed and get_portfolio_issues it is optional and only club or player work, but get_share_balances_detailed requires it when you use search or issue. get_share_balance_by_user_club has no share_type.
• The REST endpoints /messages, /transfers/counts and /club_balance_sheet/weeks require season_id (they answer 422 without it), but the matching MCP tools default to the current season. Use get_seasons to list valid season ids. To find the current season, read seasonId from /v1/bootstrap. get_messages needs at least one of country_id, comp_id or club_id.

#Tool domains

Each table lists a tool and its key parameters. Most tables also have an Upstream column that says where the same data can be read directly. The name lookups have none, because they search the datapack. tools/list has the full schema of every tool. The Overview explains how to call the hosted APIs.

• REST: a path on the Datacentre REST API, added to https://play.soccerverse.com/datacentre. Most apps start here.
• Unified API: a /v1 path, added to https://play.soccerverse.com. These are ready-made, page-sized reads.
• GSP: a read method of the game-state processor, sent as JSON-RPC with POST https://play.soccerverse.com/v1/gsp (see GSP JSON-RPC). Use it only when the REST API has no equivalent. A method marked "raw only" is not served there: use the MCP tool, or run your own node. A GSP call, on /v1/gsp or on your own node, differs from the MCP tool in four ways:
  • share is an object, {"club": 50} or {"player": 1100}. The club_50 string exists only in MCP.
  • Money values are raw integers: divide by 10,000.
  • Pass every parameter. MCP fills in defaults such as the current season and GSP does not: get_club_schedule without season_id is an error. To find the current season, read seasonId from /v1/bootstrap.
  • Replies arrive in the state envelope, with the payload in result.data.
• GraphQL: a query on one of the public subgraphs. "Democrit GraphQL" is the Democrit/SVC subgraph, and "Shop GraphQL" is the shop, referrals and pricing subgraph.
• Composite: the tool combines several calls into one.

#Name resolution

Look up ids from names. Names are matched against the public datapack (see Datapack and assets).

Example MCP call:

{
  "name": "resolve_club_name",
  "arguments": { "name": "Manchester United", "limit": 5 }
}

Response notes: ranked matches with ids and confidence scores. Treat fuzzy matches as candidates, not proof. The game uses its own names: real-world "Manchester United" resolves to Manchester Red (id 33, confidence 0.84), leagues are named like "ENG Division 1", and real-world names such as "Premier League" return an empty list.

#Clubs

Club details, lists, job postings, squads, schedules, tactics, fixtures, league membership, history, balance sheets, messages, loans, transfers and tactical analysis.

Example MCP tool call:

{
  "name": "get_club_details",
  "arguments": { "club_id": 50 }
}

Response notes: REST club records include balance, fans_current, stadium_size_current, manager_name, default_formation, transfers_in/out, country/division fields, and share/market values. GSP fixture rows include fixture_id, turn_id, date, home/away clubs, goals, comp metadata, and played.

#Players

Search players and get details, transfer, loan, morale and history data, competition statistics, squad membership, and player ROI analytics.

Example MCP tool call:

{
  "name": "get_player_details",
  "arguments": { "player_id": 1100 }
}

Response notes: get_comp_player_data returns {"leagues": [...], "cups": [...]}, one row per competition and season. Player records include availability (fitness, injured, banned), ratings (rating, rating_gk, rating_tackling, rating_passing, rating_shooting and more), position fields, wages, contract, morale, and club and agent details. Some money and volume numbers are raw, see Money values.

#Users and managers

Inspect user profiles, trading stats, activity, balance sheets, achievements, rankings, referrals, portfolios, manager history and manager competition history.

Example MCP tool call:

{
  "name": "get_user_details",
  "arguments": { "username": "snailbrain" }
}

Response notes: user detail records include name, balance, last-active timestamps, managed club_id, trade volume fields, and milestone trade dates.

#Market and shares

Inspect world market data, share balances, trading graphs and history, orderbooks, user orders, top traders, SVC trades and pre-aggregated order dumps.

Example MCP tool call:

{
  "name": "get_share_balances",
  "arguments": { "club_id": 50, "share_type": "club", "page": 1 }
}

Response notes:

• Share balances identify the holder by name (a username). There is no user-id field. Rows include share_type, share_id, num, last_price, country/league/division, and manager and agent names where available.
• The raw REST dumps return {meta, data}. For /dumps/share_orders/..., data is keyed by share id and each row is [order_id, name, is_ask, price, num]. meta.fields names the columns.
• get_share_orders_dump reshapes that into {share_type, updated, requested, orderbooks_returned, no_orderbook, orderbooks}. Each orderbook has bids and asks lists of {order_id, name, is_ask, price, num, price_svc, price_short}.

#Fixtures, competitions, leagues, and reference data

Discover seasons, countries, leagues, league tables, cups, associations, fixtures, match events and commentary, match player data, and recent competitions.

Example MCP tool call:

{
  "name": "get_league_tables",
  "arguments": { "country_id": "ENG", "division": 1 }
}

Response notes: league-table rows include club_id, league_id, manager_name, country_id, division, played, won, drawn, lost, goals_for, goals_against, pts, form, season_id, stadium_size and fanbase.

#Transfers

Inspect the transfer market, active transfer auctions, club and player transfer history, auction details, transfer counts, and recent completed moves.

Example MCP tool call:

{
  "name": "get_top_transfer_auctions",
  "arguments": { "num": 5 }
}

Response notes: auction rows include transfer_auction_id, player_id, club_id, minimum_bid, high_bid, rating, position, age/date fields, and status flags. get_transfer_market returns {items, page, perPage, total, totalPages, totalListed, bidRange}. get_all_transfer_history returns {transfers, metadata}, and metadata.total_in_season counts every completed transfer of the season.

#Votes

Inspect votes and proposals globally, by user, or by club or player share.

Example MCP tool call:

{
  "name": "get_user_active_proposals",
  "arguments": { "username": "snailbrain" }
}

Response notes: get_all_votes and get_votes_for_shareholder rows include share (with share_name), type, state, start_time and end_time, plus readable date fields. get_votes_for_club_or_player rows have no share. They carry proposal_id, type, state, start_time, end_time, options with vote counts, and total_votes. get_user_active_proposals returns {items, total, note}.

#Shop

Inspect Soccerverse pack purchases and club sale and tranche status.

Example MCP tool call:

{
  "name": "get_sale_clubs",
  "arguments": { "club_id": 50, "limit": 5 }
}

Response notes:

• get_shop_purchases returns {purchases, count, note}. Each purchase has receiver, num_packs, usd_spent (a string such as "$47", raw value in usd_spent_raw), club_id, club_name, date and timestamp, and sometimes tier. club_shares_minted_total and club_tranche_remaining are the club's current state, repeated on every row. They are not per-purchase figures.
• get_sale_clubs returns {sale_clubs, count, total, page}. Each entry has club_id, country_id, tier, status, tranche, tranche_remaining, price_per_pack (such as "$49.50", raw value in price_per_pack_raw), max_packs, club_name and pack_contents, a list of {club_id, shares_per_pack, price_per_share, club_name}. With a club_id filter the entries are packs that contain that club's shares, so an entry's own club_id can be a different club.
• get_club_packs returns {updated, total_packs, total_matching, returned, packs}.

#Analytics and leaderboards

Aggregate market stats, earnings leaderboards, ROI/payback analytics, tactical analysis, rich, best-manager and top-trader lists, referrals, and ticker data.

Example MCP tool call:

{
  "name": "get_player_earnings",
  "arguments": { "threshold": 5, "limit": 5, "sort": "payback" }
}

Response notes:

• The raw REST dumps (/dumps/*) return {meta, data}. data holds rows and meta.fields names the columns.
• The MCP tools reshape them. get_player_earnings returns {meta, players} with one object per player. get_club_earnings, get_club_seller_opportunities and get_club_earnings_light return {updated, returned, clubs} plus a total (total_matching or total_clubs).

#Running your own node

Everything above is hosted by Soccerverse: the MCP server on mcp.soccerverse.com and the APIs on play.soccerverse.com. If you run your own node, you talk to its raw GSP JSON-RPC interface instead, with nothing in front of it: no cache, no /datacentre, no /v1 and no /events. Every GSP method named in the tables above works there, including the ones marked "raw only". The GSP JSON-RPC page has the full method list and says which methods are switched off by default.

Send JSON-RPC 2.0 POST requests to http://localhost:8600/. By default a node only accepts connections from its own machine (with Docker, from inside its own container). To reach it from elsewhere, start it with --nogame_rpc_listen_locally. Pass parameters as a JSON object and follow the GSP call rules in Tool domains. Two examples:

# A player's payouts (raw values, see Money values)
curl -sS http://localhost:8600/ \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"get_player_payouts","params":{"player_id":1100}}'

# The votes a user can take part in
curl -sS http://localhost:8600/ \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"get_votes_for_shareholder","params":{"name":"snailbrain"}}'