Getting Started

This guide takes you from a fresh clone to a working AI assistant that can read your EVE Online account and act on it when you ask.

1. Prerequisites

uv — the Python project/dependency manager familiar is built around. Install it first (see the uv docs for your platform).
Python 3.11+ — uv will fetch a suitable interpreter if you don't have one.
An EVE Online account (for the authenticated tools; public market/universe lookups work without one).
An MCP-capable client: Claude Code, Claude Desktop, Cowork, or any other MCP client.

2. Install

uv sync          # install the project and all dependencies (incl. the dev group)

There is no separate build step for local use. uv run familiar runs the server straight from source.

3. Log in (EVE SSO)

familiar uses EVE's Single Sign-On with PKCE — no client secret, nothing to configure. Run the login once per character:

uv run familiar login    # opens your browser to the EVE SSO consent page

The browser opens CCP's login page. Approve the requested scopes; the callback lands on localhost:8765, the code is exchanged for tokens, and the (rotating) refresh token is stored encrypted on disk. You'll see a "login complete" page — close the tab and return to the terminal.

To add more characters, switch EVE accounts in the browser and run login again. All characters live in one encrypted store:

uv run familiar status   # list logged-in characters
uv run familiar logout NAME   # forget one character (by name or id)
uv run familiar logout        # forget ALL characters

Changing scopes: if the set of requested scopes changes (e.g. a new familiar version adds tools), you must log in again to grant them.

See Authentication for the full flow and the scope list.

4. Connect to your AI client

Claude Code

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

Claude Desktop

Add this to claude_desktop_config.json (replace the directory with your clone's absolute path):

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

The client launches uv run familiar with no arguments, which starts the MCP server over stdio — the transport MCP clients speak.

5. First queries

Ask in natural language. The AI picks the right tools:

"Is the familiar server up?" → calls ping.
"What's Tritanium worth in Jita?" → get_market_price.
"Compare Plex prices across all trade hubs." → compare_hubs.
"How much ISK do I have across all my characters?" → wallet tools, per character.
"Where are my characters right now?" → location tools.
"Set a waypoint to Amarr for my main." → set_waypoint (a write — previewed first; see below).

6. Write actions

Write tools (send mail, set waypoints, edit contacts/fittings, fleet commands, open windows, PI) are enabled by default, but every write is still previewed unless you pass confirm=true, and each executed write is logged. To block all writes globally:

uv run familiar writes disable    # turn writes off
uv run familiar writes enable     # turn them back on
uv run familiar writes            # show current state

Full details in Write Safety.

7. Verify everything works

uv run pytest          # full test suite (fails under 80% coverage)
uv run familiar        # start the server manually (Ctrl-C to stop) — it waits on stdio

If uv run familiar starts without error and familiar status shows your characters, you're ready.

3.7 KiB Raw Blame History