# Local quickstart (stdio)

The local transport runs AegisGitea-MCP on your own machine as a single-user MCP
server over stdio. It authenticates with **your** Gitea Personal Access Token
(PAT) — there is no OAuth, no public endpoint, and no web stack to install.

## What you need

- A Gitea instance URL (`GITEA_URL`).
- A Gitea Personal Access Token (`GITEA_TOKEN`) with least privilege:
  - `read:repository`
  - `write:repository` only if you intend to enable `WRITE_MODE`.
- [`uv`](https://docs.astral.sh/uv/) (for `uvx`) or `pip`.

## Run it

With `uvx` (no install):

```bash
GITEA_URL=https://git.hiddenden.cafe \
GITEA_TOKEN=<pat> \
uvx aegis-gitea-mcp
```

With pip:

```bash
pip install aegis-gitea-mcp
GITEA_URL=https://git.hiddenden.cafe GITEA_TOKEN=<pat> aegis-gitea-mcp
```

A local `.env` file is also supported — drop `GITEA_URL` and `GITEA_TOKEN` in it
and just run `aegis-gitea-mcp`.

If a required variable is missing the server exits with a clear message instead
of a traceback.

## Wire it into a client

Claude Code:

```bash
claude mcp add aegis-gitea \
  -e GITEA_URL=https://git.hiddenden.cafe \
  -e GITEA_TOKEN=<pat> \
  -- uvx aegis-gitea-mcp
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "aegis-gitea": {
      "command": "uvx",
      "args": ["aegis-gitea-mcp"],
      "env": {
        "GITEA_URL": "https://git.hiddenden.cafe",
        "GITEA_TOKEN": "<pat>"
      }
    }
  }
}
```

## What still applies locally

The local adapter is single-user and trusts the PAT owner, so it skips the
per-user repository-permission probe used by the public server. Everything else
is identical to the server:

- **Policy engine** (`policy.yaml`) — same allow/deny rules.
- **`WRITE_MODE`** — off by default; writes are denied unless explicitly enabled
  and whitelisted.
- **`gitea_request`** full-API escape hatch — same write classifier, known-path
  gate, and admin/credential denylist.
- **Secret sanitization** of tool output.
- **Tamper-evident audit log** — written to a per-user path when the container
  default is not writable:
  - Windows: `%LOCALAPPDATA%\aegis-gitea-mcp\audit.log`
  - Linux/macOS: `$XDG_STATE_HOME/aegis-gitea-mcp/audit.log` or
    `~/.local/state/aegis-gitea-mcp/audit.log`
  - Override with `AUDIT_LOG_PATH`.

## Enabling writes locally

Writes are opt-in, exactly as on the server:

```bash
GITEA_URL=https://git.hiddenden.cafe \
GITEA_TOKEN=<pat-with-write-repository> \
WRITE_MODE=true \
WRITE_REPOSITORY_WHITELIST=acme/app,acme/docs \
uvx aegis-gitea-mcp
```

See [configuration.md](configuration.md) for the full variable reference and
[write-mode.md](write-mode.md) for the write-mode model.