Getting started

This page takes you from a fresh clone to a working server in about 5 to 10 minutes, most of it creating the Gitea token. It covers the local stdio setup (one user, started by your MCP client) and the HTTP server.

Prerequisites

Python 3.10 or newer and uv
A Gitea instance and a site-admin token. In Gitea: Settings, Applications, Generate New Token, then set every scope to Read and Write (or choose all). Admin features need a site-admin token. A narrower token still works: calls outside its scopes return Gitea's 403 (see "Token scopes" in the README).

1. Install and run setup

git clone https://git.hiddenden.cafe/Hiddenden/AegisGitea-MCP.git
cd AegisGitea-MCP
uv sync
uv run aegis-gitea-mcp setup

Setup prompts for the Gitea URL and the token (hidden input). For unattended use pass --gitea-url, set GITEA_TOKEN in the environment and add --yes. Options:

Option	Meaning
`--gitea-url`	Gitea base URL
`--public-base-url`	Public https URL of this server. Enables registration of the OAuth application
`--no-oauth`	Do not create the Gitea OAuth application
`--env-file`	Env file to create or update (default `./.env`)
`--template`	Env template (default `./.env.example`, else the copy built into the package)
`--yes`	Never prompt, and accept regenerating an OAuth client secret

What it does, in order:

Checks that Gitea is reachable (GET /api/v1/version) and prints the version. DNS, TLS, timeout and refused-connection failures get a specific hint.
Validates the token (GET /user), requires a site administrator, and reads its scopes (GET /token). Missing scopes are an error; all satisfies everything.
With a public base URL: creates (or reuses, or after confirmation updates) the aegis-gitea-mcp OAuth application with redirect URI <public base URL>/oauth/callback. Gitea regenerates the client secret on update, which is why it asks first.
Writes the env file atomically with mode 0600. It generates MCP_BEARER_TOKEN and TOKEN_ENCRYPTION_KEY when they are not there yet, keeps values it does not manage, and tightens the permissions of an existing file.
Prints client configurations for Claude Code, Claude Desktop and Cursor, claude.ai and Mistral Le Chat, a docker-compose service and a Caddyfile.

Secrets are only written to the env file; setup never prints them. It does not follow redirects, so the token cannot be sent to a host you did not name.

2. Run the server

stdio is started by your MCP client, so you normally do not run it by hand. To check that it starts:

uv run aegis-gitea-mcp serve

It waits for JSON-RPC on stdin (stdout is reserved for the protocol, logs go to stderr). Stop it with Ctrl+D.

For HTTP:

MCP_TRANSPORT=http uv run aegis-gitea-mcp serve     # or: serve --transport http
curl http://127.0.0.1:8080/health

It binds to 127.0.0.1:8080 and serves the MCP endpoint at /mcp. Without MCP_BEARER_TOKEN or OAuth the loopback endpoint is unauthenticated, which is only acceptable for local experiments; the server prints a warning. Setup generates MCP_BEARER_TOKEN for you.

3. Connect a client

Use the snippets that setup printed. They are also in the README. Local clients use the stdio configuration with GITEA_URL and GITEA_TOKEN in the client's env. Remote clients use https://<your host>/mcp with the bearer token or OAuth. Before exposing the server beyond localhost, read deployment.md and hardening.md.

4. Try it

Ask the client something that needs a tool, for example "list my repositories". Every result names the identity that made the call. To check the audit trail:

make validate-audit

Running without a clone

With uvx, no checkout is needed:

GITEA_URL=https://git.example.com GITEA_TOKEN=<your-gitea-token> uvx aegis-gitea-mcp

The package comes from the Gitea package registry, see packaging.md.

Where state lives

The audit log and, in OAuth mode, the encrypted token store live in DATA_DIR (default ~/.local/state/aegis-gitea-mcp). Override with DATA_DIR or AUDIT_LOG_PATH.

4.2 KiB Raw Blame History