eventor-mcp

An MCP server that exposes the full Eventor orienteering API as tools, so Claude and other MCP clients can query events, entries, start lists, results, clubs, members and activities, and, when you allow it, publish start and result lists.

It works with Eventor Australia (the default), Sweden, Norway and IOF, or any Eventor install via a custom base URL.

Coverage

Every endpoint on each instance's API documentation page has a tool. Endpoints that only one instance offers are only registered for that instance.

✏️ = writes to Eventor. These tools are marked destructive and need confirm: true, which the model should only set after you approve the change. Set EVENTOR_READ_ONLY=true to hide them completely.

The organiser export/import endpoints aren't in Eventor's public docs. Event software such as MeOS uses them, and they may behave differently between instances. On Eventor Australia, all seven exports work with a club API key (tested November 2026).

What the API can't do

Eventor's API can't create or edit events, classes, entry fees, documents or entries, and it can't change an event's status. On the website these are only HTML forms behind a CAPTCHA-protected login, with no API equivalent. The only writes the API supports are competitor settings and start list/result list uploads, and this server covers all three. The import tools haven't been tested, because they publish data.

Tested against Eventor Australia

Every read tool was called against real Newcastle Orienteering Club data, and all returned data except one: get_competitor returned 403 for competitor IDs and an empty element for person IDs. Use list_competitors instead. get_activity wasn't tested because the club has no activities in Eventor, and get_external_login_url wasn't called because it creates a real login link. The write tools haven't been run.

Responses are converted from Eventor's XML to compact JSON. Pass raw: true to get the XML unchanged, for example to load an IOF XML start list into event software. GET responses are cached for 5 minutes, as Eventor's terms of use ask.

Related MCP server: Tulospalvelu MCP

Setup

You need Node.js 20+ and your club's Eventor API key. A club administrator can find it in Eventor under the organisation's admin settings.

git clone https://github.com/JustinStafford/eventor-mcp.git
cd eventor-mcp
npm install
npm run build

Claude Code

claude mcp add eventor --scope user -e EVENTOR_API_KEY=your-key -- node /path/to/eventor-mcp/dist/index.js

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "eventor": {
      "command": "node",
      "args": ["/path/to/eventor-mcp/dist/index.js"],
      "env": { "EVENTOR_API_KEY": "your-key" }
    }
  }
}

Instead of putting secrets in the client config, you can put them in a .env file (see .env.example). The server checks the directory it runs from, then its own install directory (the clone), then ~/.config/eventor-mcp/.env. Variables already set in the environment take precedence. .env is git-ignored.

Configuration

Credentials are only read from the environment. They never appear in tool arguments or results.

Things to know

• Your own club only. An API key belongs to one organisation. Members, competitors, memberships, activities, external login links and club starts/results only work for that organisation's ID. Call get_api_key_organisation first to find it.

• Keep queries narrow. list_organisations, list_entries and results with split times can be very large. Use date ranges, IDs and top. list_organisations also has local filters (nameContains, organisationTypeIds, parentOrganisationId) that are applied after the download.

• Dates are yyyy-mm-dd or yyyy-mm-dd hh:mm:ss. A date-only "from" starts at 00:00:00 and a date-only "to" ends at 23:59:59.

Development

npm test          # vitest, with Eventor mocked
npm run typecheck
npm run build

Tools are generated from the endpoint table in src/endpoints.ts. To support a new endpoint, add an entry there.

License

MIT