gogs-mcp

Gogs MCP Server

A Model Context Protocol (MCP) server that provides access to Gogs git hosting APIs. This server enables AI assistants like Claude to interact with Gogs repositories, users, and other resources.

Features

This MCP server provides tools to:

• User Management

  • Get authenticated user information
  • Get specific user details
  • Search for users

• Repository Management

  • List user repositories
  • Search repositories
  • Get repository information
  • Create new repositories
  • Delete repositories

• Content Access

  • Get file and directory contents
  • Get raw file content
  • List repository branches
  • Get commit history
  • Get git trees (low-level repository structure access)

• Issue Management

  • List issues in a repository
  • Get specific issue details
  • Create new issues
  • Update existing issues (including state changes)
  • List comments on issues
  • Add comments to issues
  • Edit existing comments

• Label Management

  • List all labels in a repository
  • Get specific label details
  • Create new labels
  • Update existing labels
  • Delete labels
  • List labels on an issue
  • Add labels to an issue
  • Remove labels from an issue
  • Replace all labels on an issue
  • Remove all labels from an issue

• Milestone Management

  • List all milestones in a repository
  • Get specific milestone details
  • Create new milestones
  • Update existing milestones
  • Delete milestones

• Organization Management

  • List organizations for authenticated user
  • Create new organization
  • List public organizations for a user
  • Get organization details
  • Update organization information
  • Add/update organization member with role

• Team Management

  • List teams in an organization
  • Create new team
  • Get team details
  • Add member to a team
  • Remove member from a team

• Release Management

  • List releases for a repository

• Public Key Management

  • List public SSH keys for a user
  • List authenticated user's public SSH keys
  • Get details of a specific public SSH key
  • Create new public SSH key
  • Delete public SSH key

• Deploy Key Management

  • List all deploy keys for a repository
  • Get details of a specific deploy key
  • Create new deploy key (read-only or read-write)
  • Delete deploy key

• User Followers

  • List followers of a user
  • List users that a user is following
  • Check if authenticated user is following a target user
  • Follow a user
  • Unfollow a user

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn
• A Gogs server instance
• Gogs access token (optional, but recommended for authenticated access)

OR

• Docker and Docker Compose (for containerized deployment)

Setup

1. Clone this repository:

   git clone ssh://git@207.154.220.231:10022/claude/gogs-mcp.git
   cd gogs-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Docker Setup

1. Clone this repository:

   git clone ssh://git@207.154.220.231:10022/claude/gogs-mcp.git
   cd gogs-mcp
   

2. Create a .env file from the example:

   cp .env.example .env
   

3. Edit .env and configure your Gogs server URL and access token:

   GOGS_SERVER_URL=https://your-gogs-server.com
   GOGS_ACCESS_TOKEN=your-access-token-here
   

4. Build and run with Docker Compose:

   docker-compose up -d
   

Or build the Docker image manually:

   docker build -t gogs-mcp-server .
   docker run --env-file .env gogs-mcp-server

Configuration

Generate Gogs Access Token

1. Log in to your Gogs instance
2. Navigate to Settings → Applications
3. Create a new access token with appropriate permissions
4. Copy the token for use in configuration

Environment Variables

Create a .env file or set environment variables:

GOGS_SERVER_URL=https://your-gogs-server.com
GOGS_ACCESS_TOKEN=your-access-token-here

# Transport mode (optional, default: stdio)
TRANSPORT_MODE=stdio  # or 'http' for HTTP/SSE transport

# HTTP server configuration (only used when TRANSPORT_MODE=http)
HTTP_PORT=3000
HTTP_HOST=0.0.0.0

The access token is optional but recommended. Without it:

• User email fields may be empty (anti-spam measure)
• Some operations requiring authentication will fail
• Only public repositories will be accessible

Transport Modes

The server supports two transport modes:

stdio (default): For use with MCP clients like Claude Desktop

• Communicates via standard input/output
• Runs as a subprocess of the MCP client
• Suitable for desktop applications

http: For HTTP-based access with Server-Sent Events (SSE)

• Exposes HTTP endpoints for the MCP protocol
• Runs as a standalone web server
• Suitable for web applications and remote access
• Supports CORS for cross-origin requests

Usage

With Claude Desktop (stdio mode)

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gogs": {
      "command": "node",
      "args": ["/absolute/path/to/gogs-mcp-server/dist/index.js"],
      "env": {
        "GOGS_SERVER_URL": "https://your-gogs-server.com",
        "GOGS_ACCESS_TOKEN": "your-access-token-here",
        "TRANSPORT_MODE": "stdio"
      }
    }
  }
}

HTTP Mode

To run the server in HTTP mode for web applications:

1. Set the transport mode to HTTP in your .env file:

   TRANSPORT_MODE=http
   HTTP_PORT=3000
   HTTP_HOST=0.0.0.0
   

2. Start the server:

   npm start
   

3. The server will be available at:

   • SSE endpoint: http://localhost:3000/sse
   • Message endpoint: http://localhost:3000/message
   • Health check: http://localhost:3000/health

4. Connect your MCP client to the SSE endpoint to establish a persistent connection.

HTTP Mode with Docker

# Set environment variables in .env
TRANSPORT_MODE=http
HTTP_PORT=3000

# Run with docker-compose
docker-compose up -d

# Or run with Docker directly
docker run -p 3000:3000 \
  -e GOGS_SERVER_URL=https://your-gogs-server.com \
  -e GOGS_ACCESS_TOKEN=your-access-token-here \
  -e TRANSPORT_MODE=http \
  -e HTTP_PORT=3000 \
  gogs-mcp-server:latest

With Other MCP Clients (stdio mode)

The server uses stdio transport and can be integrated with any MCP-compatible client:

# Set environment variables
export GOGS_SERVER_URL=https://your-gogs-server.com
export GOGS_ACCESS_TOKEN=your-access-token-here
export TRANSPORT_MODE=stdio

# Run the server
npm start

With Docker

You can use the Docker image with MCP clients by mounting it as a command:

{
  "mcpServers": {
    "gogs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "GOGS_SERVER_URL=https://your-gogs-server.com",
        "-e", "GOGS_ACCESS_TOKEN=your-access-token-here",
        "gogs-mcp-server:latest"
      ]
    }
  }
}

Or using docker-compose:

{
  "mcpServers": {
    "gogs": {
      "command": "docker-compose",
      "args": [
        "-f", "/absolute/path/to/gogs-mcp-server/docker-compose.yml",
        "run",
        "--rm",
        "gogs-mcp-server"
      ]
    }
  }
}

Available Tools

User Tools

get_current_user

Get information about the authenticated user.

get_user

Get information about a specific user.

• username (string, required): Username to look up

search_users

Search for users by username.

• query (string, required): Search query
• limit (number, optional): Maximum results (default: 10)

list_user_emails

List email addresses for the authenticated user. Returns all email addresses associated with your account, including their verification status and whether they are set as primary.

add_user_emails

Add new email address(es) to the authenticated user's account.

• emails (array of strings, required): Array of email addresses to add

delete_user_emails

Delete email address(es) from the authenticated user's account.

• emails (array of strings, required): Array of email addresses to delete

Repository Tools

list_user_repositories

List repositories for a user.

• username (string, optional): Username (omit for authenticated user)

search_repositories

Search for repositories.

• query (string, required): Search query
• uid (number, optional): User ID to filter by
• limit (number, optional): Maximum results (default: 10)
• page (number, optional): Page number (default: 1)

get_repository

Get information about a specific repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name

create_repository

Create a new repository.

• name (string, required): Repository name
• description (string, optional): Repository description
• private (boolean, optional): Create as private (default: false)
• auto_init (boolean, optional): Initialize with README (default: false)
• gitignores (string, optional): Gitignore templates (e.g., "Go,VisualStudioCode")
• license (string, optional): License template (e.g., "MIT License")
• readme (string, optional): README template (default: "Default")

delete_repository

Delete a repository (requires admin access).

• owner (string, required): Repository owner username
• repo (string, required): Repository name

Content Tools

get_contents

Get file or directory contents from a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• path (string, required): File or directory path
• ref (string, optional): Branch, tag, or commit SHA (default: default branch)

get_raw_content

Get raw file content from a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• ref (string, required): Branch, tag, or commit SHA
• path (string, required): File path

list_branches

List all branches in a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name

get_commits

Get commit history from a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• sha (string, optional): Branch name or commit SHA
• page (number, optional): Page number (default: 1)

get_tree

Get a git tree by SHA - provides low-level access to repository structure at a specific commit or tree SHA. Returns tree entries including files (blobs), directories (trees), and submodules (commits) with their modes and permissions.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• sha (string, required): Git tree SHA or commit SHA

Issue Management Tools

list_issues

List issues in a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• state (string, optional): Filter by state - 'open', 'closed', or 'all' (default: 'open')
• labels (string, optional): Comma-separated list of label names
• page (number, optional): Page number (default: 1)
• per_page (number, optional): Results per page (default: 30)

get_issue

Get a specific issue by number.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• number (number, required): Issue number

create_issue

Create a new issue in a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• title (string, required): Issue title
• body (string, optional): Issue description
• assignee (string, optional): Username to assign the issue to
• milestone (number, optional): Milestone ID
• labels (array of numbers, optional): Array of label IDs

update_issue

Update an existing issue (including closing or reopening).

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• number (number, required): Issue number
• title (string, optional): Issue title
• body (string, optional): Issue description
• assignee (string, optional): Username to assign the issue to
• milestone (number, optional): Milestone ID
• state (string, optional): Issue state - 'open' or 'closed'
• labels (array of numbers, optional): Array of label IDs

list_issue_comments

List all comments on an issue.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• number (number, required): Issue number

create_issue_comment

Add a comment to an issue.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• number (number, required): Issue number
• body (string, required): Comment text

update_issue_comment

Edit an existing comment on an issue.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• commentId (number, required): Comment ID
• body (string, required): Updated comment text

Label Management Tools

list_labels

List all labels in a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name

get_label

Get a specific label by ID.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• labelId (number, required): Label ID

create_label

Create a new label in a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• name (string, required): Label name
• color (string, required): 7-character hex color code with leading # (e.g., #ff0000)

update_label

Update an existing label.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• labelId (number, required): Label ID
• name (string, optional): Label name
• color (string, optional): 7-character hex color code with leading # (e.g., #ff0000)

delete_label

Delete a label from a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• labelId (number, required): Label ID

list_issue_labels

List all labels on a specific issue.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• number (number, required): Issue number

add_issue_labels

Add labels to an issue.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• number (number, required): Issue number
• labels (array of numbers, required): Array of label IDs to add

remove_issue_label

Remove a specific label from an issue.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• number (number, required): Issue number
• labelId (number, required): Label ID to remove

replace_issue_labels

Replace all labels on an issue with a new set.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• number (number, required): Issue number
• labels (array of numbers, required): Array of label IDs to set (replaces all existing labels)

remove_all_issue_labels

Remove all labels from an issue.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• number (number, required): Issue number

Milestone Management Tools

list_milestones

List all milestones in a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name

get_milestone

Get a specific milestone by ID.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• milestoneId (number, required): Milestone ID

create_milestone

Create a new milestone in a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• title (string, required): Milestone title
• description (string, optional): Milestone description
• due_on (string, optional): Due date in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)

update_milestone

Update an existing milestone.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• milestoneId (number, required): Milestone ID
• title (string, optional): Milestone title
• description (string, optional): Milestone description
• due_on (string, optional): Due date in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
• state (string, optional): Milestone state - 'open' or 'closed'

delete_milestone

Delete a milestone from a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• milestoneId (number, required): Milestone ID

Organization Management Tools

list_user_organizations

List organizations for the authenticated user.

• No parameters required

create_organization

Create a new organization.

• username (string, required): Organization username (alphanumeric, dashes, underscores)
• full_name (string, optional): Organization full name
• description (string, optional): Organization description
• website (string, optional): Organization website
• location (string, optional): Organization location

list_public_organizations

List public organizations for a specific user.

• username (string, required): Username to get public organizations for

get_organization

Get information about a specific organization.

• orgname (string, required): Organization name

update_organization

Update an organization (requires owner permissions).

• orgname (string, required): Organization name
• full_name (string, optional): Organization full name
• description (string, optional): Organization description
• website (string, optional): Organization website
• location (string, optional): Organization location

add_organization_member

Add or update organization membership (requires owner permissions).

• orgname (string, required): Organization name
• username (string, required): Username to add as member
• role (string, required): Member role - 'admin' or 'member'

Team Management Tools

list_organization_teams

List teams in an organization.

• orgname (string, required): Organization name

create_team

Create a new team in an organization (requires admin permissions).

• orgname (string, required): Organization name
• name (string, required): Team name (max 30 characters, alphanumeric with dashes and dots)
• description (string, optional): Team description (max 255 characters)
• permission (string, optional): Team permission level - 'read', 'write', or 'admin' (default: 'read')

get_team

Get information about a specific team.

• teamId (number, required): Team ID

add_team_member

Add a user to a team (requires admin permissions).

• teamId (number, required): Team ID
• username (string, required): Username to add to the team

remove_team_member

Remove a user from a team (requires admin permissions).

• teamId (number, required): Team ID
• username (string, required): Username to remove from the team

Release Management Tools

list_releases

List all releases for a repository. Returns release information including tag name, name, description, author, timestamps, and downloadable assets (attachments).

• owner (string, required): Repository owner username
• repo (string, required): Repository name

Note: Currently only read-only access to releases is supported. Create, update, and delete operations are not available in the Gogs API v1.

Collaborator Management Tools

list_collaborators

List all collaborators for a repository. Returns user information including username, full name, email, avatar URL, and their permission levels (admin, push, pull).

• owner (string, required): Repository owner username
• repo (string, required): Repository name

check_collaborator

Check if a user is a collaborator on a repository. Returns a boolean indicating whether the specified user has collaborator access.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• username (string, required): Username to check for collaborator status

add_collaborator

Add a user as a collaborator to a repository with specified permissions.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• username (string, required): Username to add as collaborator
• permission (string, optional): Permission level - 'read', 'write', or 'admin' (default: 'write')

remove_collaborator

Remove a user's collaborator access from a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• username (string, required): Username to remove as collaborator

Public Key Management Tools

list_user_keys

List all public SSH keys for a specific user. Returns key information including ID, title, key content, URL, and creation timestamp.

• username (string, required): Username to list public keys for

list_my_keys

List all public SSH keys for the authenticated user. Returns key information including ID, title, key content, URL, and creation timestamp.

Example response:

[
  {
    "id": 2,
    "title": "my-laptop-key",
    "key": "ssh-ed25519 AAAAC3Nza...",
    "url": "https://gogs.example.com/api/v1/user/keys/2",
    "created_at": "2025-10-28T11:09:29Z"
  }
]

get_public_key

Get details of a specific public SSH key by ID. Returns full key information.

• keyId (number, required): Public key ID

create_public_key

Create a new public SSH key for the authenticated user. Returns the created key with its assigned ID.

• title (string, required): Key title/name for identification
• key (string, required): The public key content in SSH public key format (e.g., "ssh-ed25519 AAAA...")

Example:

{
  "title": "My Development Key",
  "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBf... user@hostname"
}

delete_public_key

Delete a public SSH key by ID. Only the authenticated user can delete their own keys.

• keyId (number, required): Public key ID to delete

Deploy Key Management Tools

Deploy keys provide secure, repository-specific SSH access for automated deployments and CI/CD workflows. Unlike user keys, deploy keys are attached to specific repositories and can be configured as read-only or read-write.

list_deploy_keys

List all deploy keys configured for a repository. Returns key information including ID, title, key content, URL, read-only status, and creation timestamp.

• owner (string, required): Repository owner username
• repo (string, required): Repository name

Example response:

[
  {
    "id": 1,
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAA...",
    "url": "http://gogs.example.com/api/v1/repos/myuser/myrepo/keys/1",
    "title": "production-deploy",
    "created_at": "2024-01-15T10:30:00Z",
    "read_only": true
  }
]

get_deploy_key

Get details of a specific deploy key by ID. Returns full key information for the specified deploy key.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• keyId (number, required): Deploy key ID

create_deploy_key

Add a new deploy key to a repository. Deploy keys can be configured as read-only (default) for secure deployments or read-write for automated commits.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• title (string, required): Deploy key title/name for identification
• key (string, required): The public key content in SSH public key format (e.g., "ssh-rsa AAAA...")
• read_only (boolean, optional): Whether the key is read-only. Default: true. Set to false for read-write access.

Example:

{
  "owner": "myuser",
  "repo": "myrepo",
  "title": "CI/CD Pipeline",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDUbm... ci-server@example.com",
  "read_only": true
}

delete_deploy_key

Remove a deploy key from a repository. Requires admin access to the repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• keyId (number, required): Deploy key ID to delete

Webhook Management Tools

list_hooks

List all webhooks configured for a repository. Returns webhook information including ID, type, events, active status, and configuration.

• owner (string, required): Repository owner username
• repo (string, required): Repository name

Example response:

[
  {
    "id": 2,
    "type": "gogs",
    "events": ["create", "delete", "fork", "push", "issues", "pull_request", "issue_comment", "release"],
    "active": true,
    "config": {
      "content_type": "json",
      "url": "http://example.com/webhook"
    },
    "updated_at": "2025-10-30T20:50:16Z",
    "created_at": "2025-10-28T14:45:17Z"
  }
]

create_hook

Create a new webhook for a repository. Supports both Gogs and Slack webhook types with customizable event triggers.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• type (string, required): Webhook type - either "gogs" or "slack"
• config (object, required): Webhook configuration
  • url (string, required): URL to send webhook payloads to
  • content_type (string, required): Content type for payload - either "json" or "form"
  • secret (string, optional): Optional secret for webhook validation
  • channel (string, optional): Slack channel (for slack webhooks)
  • username (string, optional): Slack username (for slack webhooks)
  • icon_url (string, optional): Slack icon URL (for slack webhooks)
  • color (string, optional): Slack color (for slack webhooks)
• events (array, optional): Array of events that trigger the webhook. Available events: "create", "delete", "fork", "push", "issues", "issue_comment", "pull_request", "release". Default: ["push"]
• active (boolean, optional): Whether the webhook is active (default: false)

Example:

{
  "owner": "myuser",
  "repo": "myrepo",
  "type": "gogs",
  "config": {
    "url": "https://example.com/webhook",
    "content_type": "json",
    "secret": "mysecret"
  },
  "events": ["push", "issues", "pull_request"],
  "active": true
}

update_hook

Update an existing webhook's configuration, events, or active status.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• hookId (number, required): Webhook ID to update
• config (object, required): Webhook configuration (same structure as create_hook)
• events (array, optional): Array of events that trigger the webhook
• active (boolean, optional): Whether the webhook is active

delete_hook

Delete a webhook from a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• hookId (number, required): Webhook ID to delete

User Followers Tools

list_followers

List all followers of a specific user. Returns an array of user objects representing followers.

• username (string, required): Username to list followers for

Example response:

[
  {
    "id": 1,
    "username": "john",
    "full_name": "John Doe",
    "email": "john@example.com",
    "avatar_url": "https://example.com/avatars/john"
  }
]

list_following

List all users that a specific user is following. Returns an array of user objects.

• username (string, required): Username to list following for

Example response:

[
  {
    "id": 2,
    "username": "jane",
    "full_name": "Jane Smith",
    "email": "jane@example.com",
    "avatar_url": "https://example.com/avatars/jane"
  }
]

check_following

Check if the authenticated user is following a target user. Returns a boolean result.

• username (string, required): Username to check if authenticated user is following

Example response:

{
  "isFollowing": true,
  "username": "john",
  "message": "You are following john"
}

follow_user

Follow a user. The authenticated user will follow the target user.

• username (string, required): Username to follow

Example response:

{
  "success": true,
  "message": "Successfully followed user john",
  "username": "john"
}

unfollow_user

Unfollow a user. The authenticated user will unfollow the target user.

• username (string, required): Username to unfollow

Example response:

{
  "success": true,
  "message": "Successfully unfollowed user john",
  "username": "john"
}

Documented but Not Yet Implemented API Endpoints

The following Gogs API v1 endpoints are officially documented but not yet implemented in this MCP server. These represent potential features for future development:

Category	Endpoint	Method	Description	Documentation
User Administration	/admin/users	POST	Create a new user	Link
User Administration	/admin/users/:username	PATCH	Edit an existing user	Link
User Administration	/admin/users/:username	DELETE	Delete a user	Link
User Administration	/admin/users/:username/keys	POST	Create public key for user	Link
Repository Administration	/admin/users/:username/repos	POST	Create repository for user/org	Link
Team Administration	/admin/teams/:teamid/members	GET	List all members of a team	Link
Team Administration	/admin/teams/:teamid/repos/:reponame	PUT	Add or update team repository	Link
Team Administration	/admin/teams/:teamid/repos/:reponame	DELETE	Remove team repository	Link
Deploy Keys	/repos/:username/:reponame/keys	GET	List deploy keys	Link
Deploy Keys	/repos/:username/:reponame/keys/:id	GET	Get a deploy key	Link
Deploy Keys	/repos/:username/:reponame/keys	POST	Add a new deploy key	Link
Deploy Keys	/repos/:username/:reponame/keys/:id	DELETE	Remove a deploy key	Link

Contributing New Endpoints

If you'd like to help implement any of these endpoints:

1. Check the official Gogs API documentation for endpoint details
2. Add the method to src/gogs-client.ts with proper TypeScript types
3. Add the Zod schema and tool definition to src/server.ts
4. Test the endpoint against a real Gogs instance
5. Update this README with the new tool documentation
6. Submit a pull request

Development

Run in Development Mode

npm run dev

Build

npm run build

Watch Mode

npm run watch

API Documentation

The Gogs API documentation is included in the docs-api submodule. For more information about the Gogs REST API, see:

• Gogs API Documentation
• Local docs: docs-api/README.md

Security Considerations

• Access Tokens: Keep your access tokens secure. Never commit them to version control.
• Permissions: The access token's permissions determine what operations are available.
• Private Repositories: Access to private repositories requires authentication.
• Rate Limiting: Be aware of any rate limiting imposed by your Gogs server.

Troubleshooting

"GOGS_SERVER_URL environment variable is required"

Make sure you've set the GOGS_SERVER_URL environment variable or included it in your MCP client configuration.

"404 Not Found" errors

This can indicate:

• Invalid server URL
• Repository or user doesn't exist
• Authentication required but not provided
• Insufficient permissions

"401 Unauthorized" errors

• Check that your access token is correct and hasn't expired
• Verify the token has appropriate permissions for the operation

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Built with the Model Context Protocol SDK
• Designed for Gogs git hosting
• API documentation from gogs/docs-api