Skip to main content
Glama
@kineticist/mcp-server

@kineticist/mcp-server

by colinize
README.md
> Read-only mirror of the Kineticist MCP server. Changes are made in
> the Kineticist repo; issues and questions go to contact@kineticist.com.

# @kineticist/mcp-server

<!-- mcprush.com-8599c0cdbeddde143955a1e8 (directory ownership token; moved here from the npm description field) -->

Model Context Protocol server for the Kineticist pinball game database. Lets
AI agents like Claude, Cursor, and ChatGPT search the catalog, read game
details, and act on your own library: log plays, toggle ownership and
wishlist, set fun scores, write reviews.

**Just want to read Kineticist? You don't need this package or a key.** Add
the hosted server, `https://www.kineticist.com/api/mcp`, to your app. In Claude,
it's in the connector directory: <https://claude.ai/directory/kineticist>.
Setup for ChatGPT, Cursor and Codex: <https://www.kineticist.com/mcp>.

This package runs locally and needs a Kineticist API key. It has every tool the
hosted server has, plus tools that change your own library.

## Install

### Claude Desktop

Edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kineticist": {
      "command": "npx",
      "args": ["@kineticist/mcp-server"],
      "env": {
        "KINETICIST_API_KEY": "ki_live_..."
      }
    }
  }
}
```

### Cursor

Edit `.cursor/mcp.json` in your project (same shape as above).

### Claude Code

```bash
claude mcp add kineticist \
  --env KINETICIST_API_KEY=ki_live_... \
  -- npx @kineticist/mcp-server
```

Create an API key at <https://www.kineticist.com/settings>.

## Tools

The server exposes 23 tools: 10 for reading Kineticist and 13 for acting on
the key owner's own library. All of them call Kineticist's REST API with your
key.

### Read tools

| Tool | Description |
| --- | --- |
| `search_pinball_games` | Search and filter games with natural language |
| `get_game_details` | Full game info with editions, images, and description |
| `get_game_credits` | Design team for a game |
| `list_game_files` | Game files grouped by machine, optional machine filter |
| `get_random_game` | Random game for discovery |
| `get_pinball_stats` | Database statistics |
| `where_to_play` | Venues near a postal code or city, optionally only those with a given game |
| `search` | Search games, news, places to play, people, manufacturers, mods, Hype Index entries and creators |
| `get` | Read any Kineticist page by its link; news as headline, summary and link |
| `whats_new` | Latest news, new videos and podcasts from creators, and Hype Index moves |

Read tools return each game's and person's page on www.kineticist.com, so
answers can link back. Files download from the game page with a free
Kineticist account. Every tool carries a `title` and MCP annotations
(`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).

### Your library tools

Wrap `POST /api/v1/me/actions` and `GET /api/v1/me/state`. All act on the
data belonging to the API key owner.

| Tool | Description |
| --- | --- |
| `kineticist_get_my_state` | Read your state for a game: ownership, wishlist, plays, fun score, favorite |
| `kineticist_log_play` | Log a play with optional date, location, note, score, replay flag |
| `kineticist_toggle_ownership` | Mark as owned or no longer owned |
| `kineticist_toggle_want` | Toggle want-to-play or want-to-own |
| `kineticist_set_fun_score` | Set your fun score (0–100) |
| `kineticist_undo_last_play` | Remove the most recent play for a game |
| `kineticist_update_play_log` | Edit a logged play |
| `kineticist_delete_play_log` | Delete a logged play |
| `kineticist_toggle_favorite` | Add or remove a game from your favorites, or follow or unfollow a creator (by `promoterId` or its page slug, `promoterSlug`) |
| `kineticist_delete_fun_score` | Remove your fun score |
| `kineticist_update_ownership_details` | Edit ownership details for a game you own |
| `kineticist_submit_review` | Write or update your review of a game |
| `kineticist_delete_review` | Delete your review |

## Example conversations

Once the server is configured, your agent can answer things like:

- *"What Stern games are currently in production?"*
- *"Who designed Medieval Madness?"*
- *"Give me a random pinball machine I've never heard of."*
- *"Log that I played Godzilla at Pin Museum last night and give it an 87."*
- *"What's my state on The Addams Family?"*
- *"Undo my last play of Stranger Things."*

## Tiers

Every account has one of three tiers, and its limits are shared by all of the
account's keys (a second key doesn't add quota). **All tiers are free during
early access**; the tier just sets the ceiling.

| Tier | Burst (per second) | Per minute | Per day |
| --- | --- | --- | --- |
| `free` | 10 | 60 | 1,000 |
| `builder` | 20 | 120 | 5,000 |
| `partner` | 30 | 200 | 25,000 |

New accounts start on `free`. Agents that make dozens of calls per task burn
through a free account quickly. Email <colin@kineticist.com> with a short
note about what you're building if you need a higher ceiling.

## Full reference

- Web docs: <https://www.kineticist.com/docs/api>
- Interactive REST reference: <https://www.kineticist.com/docs/api/reference>
- OpenAPI spec: <https://www.kineticist.com/openapi.json>
- CLI: [`@kineticist/cli`](https://www.npmjs.com/package/@kineticist/cli)

## License

MIT