Getting Started

Prerequisites

Python 3.10 or higher
A running Gitea instance
A Gitea bot user with access to the repositories you want to expose
make (optional but recommended)

1. Install

git clone <repo-url>
cd AegisGitea-MCP

# Install production dependencies
make install

# Or install with dev dependencies (for testing and linting)
make install-dev

To install manually without make:

python -m venv venv
source venv/bin/activate        # Linux/macOS
# or: venv\Scripts\activate     # Windows

pip install -e .
# dev: pip install -e ".[dev]"

2. Create a Gitea Bot User

In your Gitea instance, create a dedicated user (e.g. ai-bot).
Grant that user read access to any repositories the AI should be able to see.
Generate an API token for the bot user:
- Go to User Settings > Applications > Generate Token
- Give it a descriptive name (e.g. aegis-mcp-token)
- Copy the token — you will not be able to view it again.

3. Configure

Copy the example environment file and fill in your values:

cp .env.example .env

Minimum required settings in .env:

GITEA_URL=https://gitea.example.com
GITEA_TOKEN=<your-bot-user-token>
AUTH_ENABLED=true
MCP_API_KEYS=<your-generated-api-key>

See Configuration for the full list of settings.

4. Generate an API Key

The MCP server requires clients to authenticate with a bearer token. Generate one:

make generate-key
# or: python scripts/generate_api_key.py

Copy the printed key into MCP_API_KEYS in your .env file.

5. Run

make run
# or: python -m aegis_gitea_mcp.server

The server starts on http://0.0.0.0:8080 by default.

Verify it is running:

curl http://localhost:8080/health
# {"status": "healthy", ...}

6. Connect an AI Client

ChatGPT

Use this single URL in the ChatGPT MCP connector:

http://<host>:8080/mcp/sse?api_key=<your-api-key>

ChatGPT uses the SSE transport: it opens a persistent GET stream on this URL and sends tool call messages back via POST to the same URL. The api_key query parameter is the recommended method because the ChatGPT interface does not support setting custom request headers.

Other MCP clients

Clients that support custom headers can use:

SSE URL: http://<host>:8080/mcp/sse
Tool discovery URL: http://<host>:8080/mcp/tools (no auth required)
Tool call URL: http://<host>:8080/mcp/tool/call
Authentication: Authorization: Bearer <your-api-key>

For a production deployment behind a reverse proxy, see Deployment.

Next Steps

Configuration — tune file size limits, rate limiting, log paths
API Reference — available tools and endpoints
Security — understand authentication and audit logging
Deployment — Docker and Traefik setup

2.9 KiB Raw Blame History