gitea-mcp-server/AGENTS.md

Gitea MCP Setup for OpenClaw

This guide explains how to set up Gitea MCP with per-agent Gitea account isolation in OpenClaw.

Structure

gitea-mcp/
├── mcp/           # MCP server source code (Go)
└── AGENTS.md      # This file - OpenClaw setup guide

Architecture Overview

The Gitea MCP server provides Gitea tools via the Model Context Protocol (MCP). Each MCP instance uses a single Gitea token, making it ideal for per-agent isolation.

Key Features:

• stdio mode (default): For local MCP clients
• HTTP mode: For remote MCP servers on configurable ports
• 50+ tools: repos, issues, PRs, branches, files, wiki, search, actions, commit status, repo structure

New Wave 2 Tools:

• check_gitea_version - Check Gitea server version and API capabilities
• get_workflow_file_content - Get workflow files from .gitea/workflows/ or .github/workflows/
• list_repo_structure - List complete repository structure using Git tree API
• monitor_workflow_dispatch - Dispatch and monitor workflows until completion (Gitea 1.23+)
• list_action_runners - List self-hosted action runners (Gitea 1.23+)
• create_commit_status - Create commit status checks for CI/CD
• list_action_artifacts - List and download workflow artifacts (Gitea 1.23+)

Gitea Version Compatibility:

• Gitea 1.22.5: Limited Actions API support (no artifacts, runners, or workflow monitoring)
• Gitea 1.23+: Full Actions API support including all Wave 2 tools

Setup for OpenClaw with Per-Agent Isolation

Step 1: Build the MCP Server

cd mcp
make build
cp gitea-mcp ~/.bun/bin/gitea-mcp

Step 2: Run Multiple MCP Instances

Each agent needs its own MCP server instance with its own token:

# Friday's MCP (runs on port 8081)
gitea-mcp --host https://gitea.example.com --port 8081 --token <YOUR_GITEA_TOKEN> &

# Karti's MCP (runs on port 8082)
gitea-mcp --host https://gitea.example.com --port 8082 --token <YOUR_GITEA_TOKEN> &

Step 3: Configure MCP Servers in OpenClaw

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "acpx": {
        "config": {
          "mcpServers": {
            "gitea-mcp-friday": {
              "command": "gitea-mcp",
              "args": ["--host", "https://gitea.example.com", "--port", "8081"],
              "env": {
                "GITEA_ACCESS_TOKEN": "<YOUR_GITEA_TOKEN>"
              }
            },
            "gitea-mcp-karti": {
              "command": "gitea-mcp",
              "args": ["--host", "https://gitea.example.com", "--port", "8082"],
              "env": {
                "GITEA_ACCESS_TOKEN": "<YOUR_GITEA_TOKEN>"
              }
            }
          }
        }
      }
    }
  }
}

Step 4: Add Per-Agent Tool Restrictions

The key for isolation is tools.allow/deny per agent. This guarantees each agent can only use its own Gitea MCP:

{
  "agents": {
    "list": [
      {
        "id": "friday",
        "name": "Friday Agent",
        "agentDir": "~/.openclaw/agents/friday/agent",
        "workspace": "/Users/karti/.openclaw/agents/friday/workspace",
        "tools": {
          "allow": ["gitea-mcp-friday:*", "group:fs", "group:runtime"],
          "deny": ["gitea-mcp-karti:*"]
        }
      },
      {
        "id": "karti",
        "name": "Karti Agent",
        "agentDir": "~/.openclaw/agents/karti/agent",
        "workspace": "/Users/karti/.openclaw/agents/karti/workspace",
        "tools": {
          "allow": ["gitea-mcp-karti:*", "group:fs", "group:runtime"],
          "deny": ["gitea-mcp-friday:*"]
        }
      }
    ]
  }
}

Key Points:

• allow: What tools the agent CAN use
• deny: What tools the agent CANNOT see/use
• gitea-mcp-*:* means all tools from that MCP server
• group:fs, group:runtime are built-in tool groups

Step 5: Add Agent Instructions (AGENTS.md per agent)

Create per-agent AGENTS.md to enforce behavior:

Friday's workspace (~/.openclaw/agents/friday/workspace/AGENTS.md):

# Friday Agent

You are the Friday Agent. You only have access to the gitea-mcp-friday MCP server.

When performing Git operations, use only the gitea-mcp-friday tools.
Never attempt to use gitea-mcp-karti or any other Gitea MCP server.

Karti's workspace (~/.openclaw/agents/karti/workspace/AGENTS.md):

# Karti Agent

You are the Karti Agent. You only have access to the gitea-mcp-karti MCP server.

When performing Git operations, use only the gitea-mcp-karti tools.
Never attempt to use gitea-mcp-friday or any other Gitea MCP server.

Available MCP Tools

Each MCP server provides these tools (prefixed with server name):

Category	Tools
User	get_my_user_info, get_user_orgs, search_users
Repository	create_repo, fork_repo, list_my_repos, search_repos, list_repo_structure
Branches/Tags	create_branch, delete_branch, list_branches, create_tag, list_tags
Files	get_file_content, create_file, update_file, delete_file, get_dir_content
Issues	create_issue, list_repo_issues, create_issue_comment, edit_issue
Pull Requests	create_pull_request, list_repo_pull_requests, get_pull_request_by_index
Releases	create_release, list_releases, get_latest_release
Wiki	create_wiki_page, update_wiki_page, list_wiki_pages
Search	search_repos, search_users, search_org_teams
Server	get_gitea_mcp_server_version, check_gitea_version
Actions	get_workflow_file_content, monitor_workflow_dispatch, list_action_runners, list_action_artifacts, dispatch_repo_action_workflow, list_repo_action_runs
Commit Status	create_commit_status

Note: Tools marked with (1.23+) require Gitea 1.23 or later:

• monitor_workflow_dispatch
• list_action_runners
• list_action_artifacts

Testing Per-Agent Isolation

Test with TUI for each agent:

# Test Friday (should only see gitea-mcp-friday tools)
openclaw tui --session friday --message "list available gitea tools"

# Test Karti (should only see gitea-mcp-karti tools)
openclaw tui --session karti --message "list available gitea tools"

Adding New Agents

To add a new agent (e.g., "edith"):

1. Run a new MCP instance:

gitea-mcp --host https://gitea.example.com --port 8083 --token <YOUR_GITEA_TOKEN> &

2. Add to mcpServers in openclaw.json:

"gitea-mcp-edith": {
  "command": "gitea-mcp",
  "args": ["--host", "https://gitea.example.com", "--port", "8083"],
  "env": { "GITEA_ACCESS_TOKEN": "<YOUR_GITEA_TOKEN>" }
}

3. Add agent with tool restrictions:

{
  "id": "edith",
  "name": "Edith Agent",
  "tools": {
    "allow": ["gitea-mcp-edith:*", "group:fs", "group:runtime"],
    "deny": ["gitea-mcp-friday:*", "gitea-mcp-karti:*"]
  }
}

4. Create AGENTS.md in her workspace

Troubleshooting

• Agent can't see MCP tools: Check tools.allow includes the MCP server name
• Agent sees wrong tools: Check tools.deny excludes other MCP servers
• MCP not connecting: Verify port is available and token is correct
• Token not working: Test directly: curl -H "Authorization: token <YOUR_GITEA_TOKEN>" https://gitea.example.com/api/v1/user

Environment Variables

Variable	Description	Default
GITEA_HOST	Gitea server URL	https://gitea.com
GITEA_ACCESS_TOKEN	Access token	(required)
GITEA_READONLY	Enable read-only mode	false
GITEA_DEBUG	Enable debug logging	false
GITEA_INSECURE	Allow insecure TLS	false