# valorant-mcp

> MCP server for Valorant esports — match schedules, live results, reminders, and AI-powered analysis.

Any MCP-compatible AI agent (Claude, Cursor, Windsurf, etc.) can install this and immediately ask questions like *"What matches are live right now?"*, *"Remind me before Sentinels' next match"*, or *"Who was MVP in yesterday's Champions final?"*

Data is sourced from [vlr.gg](https://vlr.gg). Analysis is powered by Claude (optional).

---

## Quickstart

```bash
# Run directly (no install)
npx valorant-mcp

# Or install globally
npm install -g valorant-mcp
```

### Add to Claude Desktop / Claude Code

```json
// ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "valorant": {
      "command": "npx",
      "args": ["valorant-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}
```

> `ANTHROPIC_API_KEY` is only required for `get_match_analysis` and `get_match_preview`. All other tools work without it.

---

## Tools

| Tool | Description |
|---|---|
| `get_upcoming_matches` | Live + upcoming matches in the next N hours |
| `get_recent_results` | Latest completed match results |
| `get_match_details` | Map-by-map scores and player stats for a match |
| `search_matches` | Search by team name, event, or region |
| `get_match_analysis` | AI-powered breakdown: MVP, key rounds, team summary |
| `get_match_preview` | Pre-match hype and context |
| `subscribe_reminder` | Set a reminder for a team or specific match |
| `list_reminders` | View all pending reminders |
| `cancel_reminder` | Remove a reminder |

---

## Example Conversations

> *"What Valorant matches are happening today?"*

> *"Remind me 10 minutes before Sentinels' next match"*

> *"Who won the Champions 2025 final and what was the score?"*

> *"Give me a full analysis of the last Team Liquid match"*

> *"What matches are live right now?"*

---

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `ANTHROPIC_API_KEY` | For analysis tools | Powers `get_match_analysis` and `get_match_preview` |
| `TELEGRAM_BOT_TOKEN` | For Pi daemon | Telegram bot token for notifications |
| `TELEGRAM_CHAT_ID` | For Pi daemon | Your Telegram chat ID |
| `DISCORD_WEBHOOK_URL` | Optional | Discord webhook for notifications |

---

## Pi Daemon (background reminders)

The MCP server handles on-demand queries from AI agents. For **automatic notifications** without needing an agent open, run the Python daemon on a Raspberry Pi or any always-on device:

```bash
pip install requests

export TELEGRAM_BOT_TOKEN="your_token"
export TELEGRAM_CHAT_ID="your_chat_id"

python3 daemon/valorant_daemon.py
```

The daemon reads reminders saved by the MCP server (`subscribe_reminder` tool) and fires notifications when a match is about to start.

### Auto-start on boot

```bash
# Edit the service file with your credentials
nano daemon/valorant-daemon.service

sudo cp daemon/valorant-daemon.service /etc/systemd/system/
sudo systemctl enable --now valorant-daemon
sudo systemctl status valorant-daemon
```

---

## Build from Source

```bash
git clone https://github.com/YOUR_USERNAME/valorant-mcp
cd valorant-mcp
npm install
npm run build
npm start

# Test with the MCP Inspector UI
npm run inspector
```

---

## Architecture

```
src/
├── index.ts              # MCP server entry point (9 tools)
├── scraper/
│   ├── vlr.ts            # vlr.gg scraper
│   └── types.ts          # Shared TypeScript interfaces
├── tools/
│   ├── matches.ts        # Match listing and search tools
│   ├── analysis.ts       # AI analysis and preview tools
│   └── reminders.ts      # Reminder management tools
├── analysis/
│   ├── claude.ts         # Anthropic API client
│   └── prompts.ts        # Analysis and preview prompt templates
└── db/
    └── index.ts          # SQLite (reminders + response cache)

daemon/
├── valorant_daemon.py    # Python background worker for Pi
└── valorant-daemon.service  # systemd service file
```

---

## How It Works

1. **Scraping** — Match data is scraped from vlr.gg on demand. Results are cached for 1 hour.
2. **Reminders** — Stored in a local SQLite DB (`~/.valorant-mcp/data.db`). The Pi daemon polls every 60 seconds and fires notifications for due reminders.
3. **Analysis** — Match stats are fed to Claude which returns a structured natural-language breakdown. Results are cached permanently (no re-billing for the same match).

---

## Where to Find MCP Servers

Looking for more MCP servers? Check these directories:

- **[Smithery](https://smithery.ai)** — largest MCP marketplace
- **[mcp.so](https://mcp.so)** — community directory
- **[Glama](https://glama.ai/mcp/servers)** — curated list
- **[awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)** — GitHub list

---

## License

MIT