# matchday-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes the
[matchday](https://github.com/mgphp/matchday) app's fixtures, match detail, league table and
squad as tools for any MCP-compatible LLM client (Claude Code, Claude Desktop, etc). It's a thin
wrapper over [matchday-api](https://github.com/mgphp/matchday-api).

## Tools

| Tool           | Wraps              | Args |
| -------------- | ------------------ | ---- |
| `get_fixtures` | `GET /fixtures`    | —    |
| `get_match`    | `GET /matches/:id` | `id` |
| `get_table`    | `GET /table`       | —    |
| `get_squad`    | `GET /squad`       | —    |

Read-only — see [docs/PROJECT_PLAN.md](docs/PROJECT_PLAN.md) for what's next.

## Setup

Requires a deployed matchday-api instance and its API key.

```bash
npm install
npm run build
```

Add it to your MCP client config (e.g. `.mcp.json`):

```json
{
  "mcpServers": {
    "matchday": {
      "command": "node",
      "args": ["/path/to/matchday-mcp/dist/index.js"],
      "env": {
        "MATCHDAY_API_URL": "https://your-function-url.lambda-url.eu-west-2.on.aws",
        "MATCHDAY_API_KEY": "your-api-key"
      }
    }
  }
}
```

Once published to npm (see project plan), `command`/`args` can instead be `npx` / `["-y", "matchday-mcp"]`.

See [`.env.example`](.env.example) for the required environment variables.

## Development

```bash
npm run typecheck
npm run lint
npm run format:check
npm test
npm run build   # compiles src/ to dist/
```

## Cost

No hosting — this runs locally as a process the MCP client spawns over stdio. It just calls the
existing matchday-api Lambda, which stays inside the AWS always-free tier.