# AcesAPI MCP server

[![Smithery](https://img.shields.io/badge/Smithery-listed-ff5601?style=flat-square)](https://smithery.ai/servers/noahowsh/AcesAPI) [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-0b7285?style=flat-square)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.noahowsh/acesapi)

**The tennis data API.** ATP and WTA singles matches with every set and tiebreak score, tournament draws round by round, player profiles, weekly rankings, head to head, surface splits, our own Elo by surface, and sportsbook moneylines on Grand Slam and Masters / WTA 1000 matches. REST API and MCP server. 500 free credits every month, no card.

Website: https://acesapi.com · Docs: https://acesapi.com/docs · Get a key: https://acesapi.com/signup

```
You:    "What is Carlos Alcaraz's record on clay against top-10 players?"
Claude: [calls get_surface_splits]

You:    "Who leads the Sinner and Alcaraz head to head, and how many of their meetings were finals?"
Claude: [calls get_head_to_head]

You:    "Which moneylines were posted for the 2025 US Open men's final?"
Claude: [calls get_matches, then get_match]
```


## Run it locally (stdio)

Most clients connect to `https://mcp.acesapi.com/mcp` directly. For a client that launches a local process instead:

```bash
git clone https://github.com/noahowsh/acesapi-mcp.git && cd acesapi-mcp && npm install
ACESAPI_API_KEY=your_key node index.js
```

```json
{ "mcpServers": { "acesapi": { "command": "node", "args": ["/path/to/acesapi-mcp/index.js"], "env": { "ACESAPI_API_KEY": "your_key" } } } }
```

It forwards to the hosted server with your key, so every tool and credit cost is the same.

## Skills

This repo also ships 16 free Claude skills in [`skills/`](skills/) that turn Claude into a tennis analyst on top of the tools below: match and player lookup, surface Elo, head to head, ranking history, set-score modeling, odds math, edge detection and backtesting. They call the AcesAPI tools and keep to what the data holds (no serve statistics, moneylines on Slams, Masters and WTA 1000 only).

```bash
git clone https://github.com/noahowsh/acesapi-mcp.git
```

Or install them as a Claude Code plugin:

```
/plugin marketplace add noahowsh/acesapi-mcp
/plugin install acesapi-skills@acesapi
```

Or with the skills CLI: `npx skills add noahowsh/acesapi-mcp`.

Point Claude at the `skills/` folder, add the MCP server (see Quick start), and ask a question such as "who is favored in tomorrow's Shanghai match and why?". Full catalog: [`skills/README.md`](skills/README.md). The skills also work on your own CSV or JSON without a key.

## Useful pages

- [Docs](https://acesapi.com/docs): every endpoint with parameters and live examples
- [Tennis odds](https://acesapi.com/odds): upcoming ATP and WTA matches with each sportsbook's moneyline
- [Data atlas](https://acesapi.com/docs/atlas): what exists and where coverage is partial
- [Guides](https://acesapi.com/guides): Python walkthroughs for surface Elo, head to head, rankings, set scores and surface splits
- [Data](https://acesapi.com/data): [results](https://acesapi.com/data/tennis-results-api), [rankings history](https://acesapi.com/data/tennis-rankings-history), [odds history](https://acesapi.com/data/tennis-odds-history)
- [Pricing](https://acesapi.com/pricing): credits per call, 500 free every month
- [Surface Elo explained](https://acesapi.com/glossary/surface-elo)
- Compare: [API Tennis](https://acesapi.com/compare/api-tennis), [ESPN's tennis feed](https://acesapi.com/compare/espn-tennis-api), [Sportradar](https://acesapi.com/compare/sportradar-tennis), [SportsDataIO](https://acesapi.com/compare/sportsdataio-tennis)

## Python

The official Python client is on PyPI: [acesapi](https://pypi.org/project/acesapi/).

```bash
pip install acesapi
export ACESAPI_API_KEY=sk_live_...
```

```python
from acesapi import Client

client = Client()

ranks = client.get_rankings(limit=5)
for row in ranks["rankings"]:
    print(row["rank"], row["name"], row["points"])
```

Typed errors for a bad key, no credits left, not found and rate limits, automatic retries, and `to_dataframe` for pandas.

## Quick start

This is a hosted (remote) MCP server over Streamable HTTP. There is nothing to install.

**Claude Code**

```bash
claude mcp add --transport http acesapi "https://mcp.acesapi.com/mcp?key=YOUR_API_KEY"
```

**Claude Desktop, Cursor and other clients**

```json
{
  "mcpServers": {
    "acesapi": {
      "url": "https://mcp.acesapi.com/mcp?key=YOUR_API_KEY"
    }
  }
}
```

The key can also be sent as an `x-api-key` header or `Authorization: Bearer`. Connecting and listing tools works without a key; calling a tool needs one.

**REST**

```bash
curl -X POST https://mcp.acesapi.com/v1/list_tournaments -H "x-api-key: YOUR_API_KEY"
```

Every tool is `POST /v1/{tool}` with a JSON body.

## Examples

Runnable Python (standard library only) and Node 18+ (no dependencies) examples live in [`examples/`](examples/):

- [`examples/python/quickstart.py`](examples/python/quickstart.py) and [`examples/node/quickstart.mjs`](examples/node/quickstart.mjs): schedule plus a headline call.
- [`examples/python/tennis_head_to_head_surface_elo.py`](examples/python/tennis_head_to_head_surface_elo.py): Two players side by side.

```bash
export ACESAPI_API_KEY=your_key
python3 examples/python/quickstart.py
node examples/node/quickstart.mjs
```

See [`examples/README.md`](examples/README.md) for details. Get a free key (500 credits a month, no card) at https://acesapi.com/signup.

## Tools (13)

| Tool | What it returns |
|------|-----------------|
| `list_tournaments` | A season's tournaments with dates, surface, status and champion |
| `search_players` | Find players by name or country |
| `get_tournament` | A tournament's draw and results, round by round, with every set |
| `get_matches` | Match results by day, tournament or season, with set and tiebreak scores |
| `get_schedule` | Upcoming and in-progress matches for the next days |
| `get_match` | One match: sets, tiebreak points, seeds, ratings and what the score says |
| `get_rankings` | Weekly ranking lists since 2007, or one player's ranking history |
| `get_ratings` | Our Elo ratings, overall or by surface |
| `get_head_to_head` | Two players' meetings, wins by surface and in finals |
| `get_surface_splits` | A player's record by surface: sets, games, tiebreaks, deciding sets |
| `get_player_stats` | A player's season statistics from scores, by round and opponent rank |
| `get_player` | Profile, ranking, ratings, career record, titles and recent matches |
| `get_player_matches` | A player's matches with scores and ratings, filtered by season, surface or opponent |

Leagues: tennis (default, ATP), wta (pass `league: "wta"` to any tool).

## Data

- ATP and WTA singles since 2007 (qualifying from 2022) with set and tiebreak scores
- Tournament draws and results round by round; weekly rankings since 2007
- Head to head, surface splits, player season statistics derived from scores, our Elo overall and by surface
- Sportsbook moneylines, returned in the `odds` array of `get_match` (there is no separate odds tool): Grand Slam matches from mid-2020 and ATP Masters and WTA 1000 matches from August 2024, pre-match, refreshed hourly; the array is empty for other tournaments
- No serve statistics (aces, double faults, break points)

Coverage by season, read live from the database: https://acesapi.com/docs

## Pricing

500 free credits every month, no card. Plans: Starter $19/mo (10,000 credits), Pro $49/mo (30,000), Scale $149/mo (125,000). Wallet top-ups from $5, never expire. https://acesapi.com/pricing

## Attribution

Surfaces and ratings are ours. Not affiliated with the ATP, WTA, ITF or any tournament.

## License

MIT for the contents of this repository. Data terms as above.

## Use with Codex

Add this repo as a Codex plugin marketplace, then install the plugin:

```bash
codex plugin marketplace add noahowsh/acesapi-mcp
```

Then open the plugin directory in Codex and install `acesapi-skills` from the `acesapi` marketplace. The plugin bundles the skills in `skills/` and the AcesAPI MCP server (https://mcp.acesapi.com/mcp). Set your key first (free at https://acesapi.com/signup):

```bash
export ACESAPI_API_KEY=your_key
```

Codex sends it as a bearer token.

## Use with Gemini CLI

```bash
export ACESAPI_API_KEY=your_key
gemini extensions install https://github.com/noahowsh/acesapi-mcp
```

The extension adds the AcesAPI MCP server (https://mcp.acesapi.com/mcp) and sends the key in the `x-api-key` header. Get a free key (500 credits a month) at https://acesapi.com/signup.