SIGN UPLOG IN
X (Twitter)LinkedInGitHubDiscordYouTube

How to connect Gitea to Claude

Connect Claude Web, Desktop and Cowork to Gitea MCP. List all open issues in your repository, create a new pull request for dev branch, and more using natural language, with authentication handled for you.

Get started for freeGet a demo
Gitea logoGitea
Api Key

Gitea is a lightweight, community-managed code hosting solution written in Go. It offers simple, fast, and self-hosted Git repository management for teams and individuals.

36 Tools

Introduction

Claude is Anthropic's AI assistant, available on the web, in the desktop app, and on mobile. Cowork is its agent for knowledge work, and it runs on all of those surfaces too. Connected to your apps, Claude can work with your files and services to accomplish complex tasks on your behalf.

This guide walks you through the easiest and most secure way to connect your Gitea account to Claude via Composio Connect, enabling it to list all open issues in your repository, create a new pull request for dev branch, get commit history for a specific file, and more such actions on your behalf without compromising your account security.

Setup is the same on Claude Web, Desktop, and Cowork, and you only need to do it once. The connector is tied to your account, so it's available in all three.

Also integrate Gitea with

Claude CodeCursorChatGPTAntigravityOpenAI Agents SDKClaude Agent SDKCodexGrok BuildVS CodeOpenCodeOpenClawHermesAtomic AgentPiDeepSeek HarnessGoogle ADKLangChainVercel AI SDKMastra AILlamaIndexCrewAIPydantic AIAutoGen

Connecting Gitea to Claude Web, Desktop, and Cowork

Two ways to add the Composio connector. Pick whichever you prefer.

1. Add with one click

Click the button. Claude opens with the Composio connector filled in. Click Add, then go to step 2.

Add to Claude

Add manually

In Claude Desktop, click Customize in the left sidebar, then select Connectors and click the + icon at the top.

Claude Desktop connectors screen with Add custom connector selected

Click Add custom connector and paste in the Composio MCP server URL:

bash
https://connect.composio.dev/mcp
Add custom connector dialog with Composio MCP server URL

2. Authorize in your browser

Click Connect. You'll be redirected to a browser window where you can authorize Composio to continue.

Composio authorization screen for Claude Web, Desktop, and Cowork

3. Connect your Gitea account

Back in Claude, ask it to connect to Gitea or give it any Gitea-related task.

For example, ask Claude to:

  • "List all open issues in your repository"
  • "Create a new pull request for dev branch"
  • "Get commit history for a specific file"

It will prompt you to authenticate and authorize access.

That's it. Composio's tools are now available in Claude, and your Gitea account is ready to use.

What is the Gitea Claude Connector, and what's possible with it?

The Gitea MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Gitea account. It provides structured and secure access to your repositories, code, pull requests, releases, and workflows, so your agent can inspect repository content, review commits and pull requests, monitor workflow runs, retrieve job logs, and dispatch workflows on your behalf.

  • Repository and code inspection: Have your agent retrieve repository details, inspect branches and their protection status, read files and directories, or examine Git trees and blobs.
  • Commit and pull request review: Direct your agent to fetch a commit by reference or SHA and review a pull request's current merge state and branch references.
  • Workflow monitoring and dispatch: Let the agent trigger workflows, list and filter workflow runs, inspect job and step outcomes, and retrieve diagnostic job logs.
  • Release and template lookup: Instruct your agent to find releases by tag and explore available license, label, and gitignore templates.
  • Instance information and content rendering: Have your agent check Gitea version and repository settings, list organizations and organization action secrets, or render Markdown and other supported markup as HTML.

Troubleshooting

1. Why does Claude not use the Composio connector for Gitea?

The connector can show as connected, but Claude must use it in each Gitea conversation.

  • Click + at the lower left of the chat, or type /.
  • Hover Connectors.
  • Turn on Composio.
  • Ask Claude to connect to Gitea again.

2. Why does Claude show an MCP server error before Gitea connects?

Claude can show Couldn't reach the MCP server or Authorization with the MCP server failed when you add the connector for Gitea.

  • Check that the connector URL is https://connect.composio.dev/mcp.
  • Connectors run from Anthropic's cloud, so your device network is usually not the problem.
  • Add the connector again from Customize > Connectors, then ask Claude to connect Gitea.
  • If it fails again, send the error and the ofid_ reference id to support@composio.dev.

3. Why does the Gitea authorization link not work?

The Composio connector is one server. Your Gitea account connects separately when Claude asks for it.

  • If the browser does not open, or the link expires, ask Claude to retry the Gitea connection.
  • Composio creates a fresh Gitea authorization link.
  • Open that link in your browser and finish the Gitea sign-in.

4. Why do Gitea actions fail after they worked before?

The Gitea connection can expire or lose permission.

  • Ask Claude to inspect the Gitea connection.
  • If the connection is unhealthy, disconnect it when Claude prompts you.
  • Reconnect the Gitea account and retry the action.
  • If Claude shows a permission prompt, approve it before Claude changes data in Gitea.
  • If the action still fails with a permission error, check that the connected account has that permission in Gitea itself.

5. How do I switch to a different Gitea account?

Claude can manage the Gitea connection for you.

  • Ask Claude to disconnect or delete the current Gitea account.
  • Ask Claude to connect Gitea again.
  • Open the new Composio authorization link for Gitea.
  • Sign in with the other Gitea account in the browser.
  • After the account connects, ask Claude to retry the Gitea task.

6. Why is my Gitea connection missing in Claude Desktop or on a Team plan?

The connector belongs to your Claude account, so your Gitea connection works in Claude Web, Desktop, and Cowork.

  • In Claude Desktop, open Customize > Connectors.
  • Next to Composio, click ⋮ and click Clear cache.
  • If Gitea tools still do not appear, click ⋮, disconnect, remove the connector, and add it again.
  • On Team or Enterprise, an Owner or Primary Owner must enable the connector before you can connect Gitea.
TOOLS

Supported Tools

Every Gitea action and event your agent gets out of the box.

Get ActivityPub Person Actor

Tool to retrieve the ActivityPub Person actor for a Gitea user.

Dispatch Workflow

Trigger a workflow_dispatch event and return the created run details.

Get Branch

Retrieve a repository branch, its commit, and effective protection state.

Get Commit

Retrieve one repository commit by Git ref or SHA.

Get Commit Status

Get the combined status and individual checks for a commit reference.

Get Current User

Return the Gitea user authenticated by the connected API token.

Get General API Settings

Tool to retrieve the Gitea instance's global API settings including pagination limits and response size constraints.

Get General Attachment Settings

Tool to retrieve the Gitea instance's global settings for file attachments including enabled status, allowed file types, size limits, and file count limits.

Get General Repository Settings

Tool to retrieve the Gitea instance's global settings for repositories including feature flags for mirroring, HTTP Git, migrations, stars, time tracking, and LFS.

Get General UI Settings

Tool to retrieve the Gitea instance's global settings for UI including default theme, allowed reactions, and custom emojis.

Get Gitignore Template Info

Tool to retrieve information about a specific gitignore template.

Get Git Object

Retrieve a repository Git tree or blob by object SHA.

Get Label Template Info

Tool to retrieve all labels from a specific label template.

Get License Template Info

Tool to retrieve information about a specific license template.

Get Node Info

Tool to retrieve the nodeinfo of the Gitea application.

Get Pull Request

Retrieve one pull request and its current merge state and references.

Get Release by Tag

Retrieve a repository release by its exact tag name.

Get Repository

Retrieve metadata and capabilities for one repository.

Get Repository Contents

Retrieve file content or directory entries from a repository path.

Get Signing Key

Tool to retrieve the default GPG signing key used by Gitea to sign commits.

Get Version

Tool to retrieve the version of the Gitea application.

Get Workflow Job

Get structured status and step details for one Gitea Actions job.

Get Workflow Job Logs

Retrieve the plain-text diagnostic log for a repository Actions job.

List Commits

List and filter commits in a repository.

List Gitignore Templates

Tool to retrieve all available gitignore templates.

List Label Templates

Tool to retrieve all available label templates.

List License Templates

Tool to retrieve all available license templates.

List Workflow Run Jobs

List jobs and step outcomes for one repository Actions workflow run.

List Workflow Runs

List and filter Actions workflow runs for a repository.

Merge Pull Request

Merge now or after checks using a selected strategy, with optional requirement bypass and source-branch deletion.

Get All Organizations

Tool to retrieve a paginated list of all organizations in the Gitea instance.

List Organization Actions Secrets

Tool to list all action secrets for an organization.

Render Markdown

Tool to render a markdown document as HTML with configurable rendering modes and context.

Render Markdown Raw

Tool to render raw markdown text as HTML.

Render Markup

Tool to render a markup document as HTML with support for multiple markup formats.

Upsert Repository File

Create, update, move, or rename a file, optionally on a new branch with force-push.

FRAMEWORKS

How to build Gitea MCP Agent with another framework

Claude Code logo

Claude Code

Use Gitea MCP with Claude Code

Cursor logo

Cursor

Use Gitea MCP with Cursor

ChatGPT logo

ChatGPT

Use Gitea MCP with ChatGPT

Antigravity logo

Antigravity

Use Gitea MCP with Antigravity

OpenAI Agents SDK logo

OpenAI Agents SDK

Use Gitea MCP with OpenAI Agents SDK

Claude Agent SDK logo

Claude Agent SDK

Use Gitea MCP with Claude Agent SDK

Codex logo

Codex

Use Gitea MCP with Codex

Grok Build logo

Grok Build

Use Gitea MCP with Grok Build

VS Code logo

VS Code

Use Gitea MCP with VS Code

OpenCode logo

OpenCode

Use Gitea MCP with OpenCode

OpenClaw logo

OpenClaw

Use Gitea MCP with OpenClaw

Hermes logo

Hermes

Use Gitea MCP with Hermes

Atomic Agent logo

Atomic Agent

Use Gitea MCP with Atomic Agent

Pi logo

Pi

Use Gitea MCP with Pi

DeepSeek Harness logo

DeepSeek Harness

Use Gitea MCP with DeepSeek Harness

Google ADK logo

Google ADK

Use Gitea MCP with Google ADK

LangChain logo

LangChain

Use Gitea MCP with LangChain

Vercel AI SDK logo

Vercel AI SDK

Use Gitea MCP with Vercel AI SDK

Mastra AI logo

Mastra AI

Use Gitea MCP with Mastra AI

LlamaIndex logo

LlamaIndex

Use Gitea MCP with LlamaIndex

CrewAI logo

CrewAI

Use Gitea MCP with CrewAI

Pydantic AI logo

Pydantic AI

Use Gitea MCP with Pydantic AI

AutoGen logo

AutoGen

Use Gitea MCP with AutoGen

FAQ

Frequently asked questions

With a standalone Gitea MCP server, the agents and LLMs can only access a fixed set of Gitea tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Gitea and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. Claude Cowork fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Gitea tools.

Yes, absolutely. You can configure which Gitea scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Gitea data and credentials are handled as safely as possible.

Start with Gitea.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Gitea tool your agent needs.Free to start.

Start building