Provides tools for interacting with Forgejo instances, enabling management of repositories, issues, pull requests, and other resources through the Forgejo API.
Provides tools for interacting with Gitea instances, enabling management of repositories, issues, pull requests, and other resources through the Gitea API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gitea-mcp-server show open issues in my repository"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol server that provides ~400 auto-generated tools and resources for LLM agents to interact with Gitea and Forgejo instances. Built with FastMCP 3.x.
Your Gitea/Forgejo instance
│
▼ (Swagger/OpenAPI spec)
gitea-mcp-server
│ ┌────────────────────────────┐
│ │ Auto-generates ~400 tools │
│ │ from the API spec │
│ │ Adds lazy loading, scope │
│ │ filtering, annotations, │
│ │ workflow guides, resources │
│ └────────────────────────────┘
│
▼ (MCP protocol: stdio or HTTP)
Your LLM agent
│
├─ call_tool("gitea_issue_create_issue", ...)
├─ read_resource("gitea://repos/owner/repo")
└─ search_tools("list pull requests")Related MCP server: GitHub MCP Server
Python 3.11+ and uv (package manager)
A Gitea or Forgejo instance (local or remote)
An API token with sufficient scopes (Settings → Applications → Generate Token)
git clone https://github.com/pxsloot/gitea-mcp-server.git && cd gitea-mcp-server
cp .env.example .env # then edit GITEA_URL and GITEA_TOKEN
uv sync
uv run python -m gitea_mcp_serverpip install git+https://github.com/pxsloot/gitea-mcp-server.git
gitea-mcpEnv var | Default | Description |
| -- | Base URL of your Gitea/Forgejo instance |
| -- | API token (Settings → Applications → Generate Token) |
|
| Set |
| -- | Custom CA bundle path |
|
|
|
|
|
|
|
|
|
|
| Prefix for all tool names |
|
| Hide tools the token's scopes cannot use |
|
| Hide tools from |
| -- | YAML file with tool/resource exclude/include patterns |
|
| Default |
HTTP transport settings (TRANSPORT_TYPE=http):
HTTP_HOST — default 127.0.0.1 (set HTTP_HOST=0.0.0.0 for remote access)
HTTP_PORT — default 8080
HTTP_PATH — default /mcp
HTTP_CORS — defaults to origin from GITEA_URL
uv run python -m gitea_mcp_serverTRANSPORT_TYPE=http uv run python -m gitea_mcp_server
# Health check: http://localhost:8080/health
# MCP endpoint: http://localhost:8080/mcpdocker build --progress=plain -t gitea-mcp-server:latest .
docker run --rm -e GITEA_URL=... -e GITEA_TOKEN=... gitea-mcp-server:latestFor a local test Gitea instance: docker compose -f docker-compose.gitea.yml up -d
Most MCP servers hand-wrap a handful of endpoints. This one is generated from your instance's own API spec and shaped for how agents actually work: it stays in lockstep with Gitea, hides what your token cannot use, and spends the minimum context to be discovered.
Generated, not hand-wrapped
Tools and resources are generated from your instance's Swagger spec (converted 2.0 → 3.1) — there is no endpoint list to fall out of date — with a small hand-written discovery layer on top.
Tool and resource metadata ride one typed registration record, checkable over the raw MCP transport.
Built for agent context
Lazy loading — ~400 tools are found through BM25 search, not listed upfront.
Succinct by default — format and detail let an agent ask for exactly
what it needs; large reads stay cheap.
Scope-aware — tools and resources your token cannot use are hidden, not discovered as failures at call time.
Views that stay honest
Markdown views are anchored to the response schema, so a new or changed type renders correctly without a hand-written formatter.
One result pipeline writes both output channels, so every tool returns a consistent shape.
Gitea-native operations
Cached, URI-addressed MCP Resources for reads
(gitea://repos/{owner}/{repo}).
Workflow guides — 16 guides for the concepts the API alone does not explain.
mcp_extensions.yaml — override tool metadata without code.
stdio + HTTP transports, Docker, and OpenTelemetry observability.
The reasoning behind these choices — and the patterns to follow when extending the server — is in docs/DESIGN.md.
# Tests
uv run pytest tests/unit/ -x -q
# Lint & format
uv run ruff check gitea_mcp_server/
uv run ruff format --check .
# Type-check
uv run mypy gitea_mcp_server/
# Coverage
uv run pytest --cov=gitea_mcp_serverSee docs/DESIGN.md, docs/ARCHITECTURE.md, and docs/DEVELOPMENT.md.
Please read CONTRIBUTING.md for the full workflow. Start with AGENTS.md for project onboarding. The docs/SKILL.md has the developer handbook with conventions, workflows, and checklists for agent contributors.
See CHANGELOG.md for release history.
Report vulnerabilities to gitea-mcp-server@pxsloot.nl — see SECURITY.md.
MIT — see LICENSE.
This server cannot be deployed
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Git-backed platform for skills, tools, and context for AI agents
A registry of AI agent tools — MCP servers, APIs, CLIs, SDKs — kept current by automated ingestion.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
