Getting Started

This page takes you from a clone to a running familiar connected to Claude.

Requirements

uv — the Python project/dependency manager familiar is built around.
Python ≥ 3.11 (uv will fetch a suitable interpreter if needed).
An EVE Online account (for the authenticated tools; the public market/universe tools work without one).

1. Install

uv sync                 # install deps (incl. the dev group)

There is no separate build step for development. uv build produces the wheel (CI does this on merge).

2. Log in (per character)

uv run familiar login   # browser EVE SSO login; run once per character
uv run familiar status  # list logged-in characters

login opens your browser, runs the EVE SSO PKCE flow, captures the callback on localhost:8765, and stores the (rotating) refresh token Fernet-encrypted on disk. Re-run login for each character — switch EVE accounts in the browser as needed; they all live in one encrypted store. Changing the requested scopes requires logging in again.

Other auth/admin subcommands:

uv run familiar logout            # forget ALL characters
uv run familiar logout NAME       # forget one character (by name or id)
uv run familiar writes            # show whether writes are enabled
uv run familiar writes disable    # block all write actions
uv run familiar writes enable     # re-allow write actions

3. Optional: offline SDE

For network-free item / system / station lookups, install a local copy of EVE's Static Data Export (the Fuzzwork SQLite conversion):

uv run familiar sde download   # download + decompress the SDE (a few hundred MB)
uv run familiar sde status     # show whether it's installed and where
uv run familiar sde path       # print the expected SDE path

Once present, get_item / get_system / get_station serve from it without hitting ESI; familiar falls back to ESI whenever the SDE is absent or doesn't know the id. See Architecture for how the fallback works.

4. Connect to Claude

Claude Code:

claude mcp add familiar -- uv --directory /path/to/familiar run familiar

Claude Desktop — add this to claude_desktop_config.json:

{
  "mcpServers": {
    "familiar": {
      "command": "uv",
      "args": ["--directory", "/path/to/familiar", "run", "familiar"]
    }
  }
}

With no arguments, familiar runs the MCP server over stdio — that's how Claude Code / Claude Desktop / Cowork launch it.

5. Ask in natural language

Once connected, just ask:

"What's Tritanium worth in Jita?"
"How much ISK across all my characters?"
"Where are my characters right now?"
"What's in my skill queue?"
"Set a waypoint to Amarr." (a write — previewed first; see Write Safety)

A good first call is ping, which confirms the server is alive and reports its version.

familiar

familiar — an EVE Online MCP server · repository · MIT