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

• Markdown Rendering

  • Render markdown text to HTML with GitHub Flavored Markdown (GFM) support
  • Render raw markdown with simple text input
  • Support repository context for issue/PR references
  • Preview documentation and content before committing

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"
}

Admin API Tools

⚠️ WARNING: These tools require administrator privileges on the Gogs instance.

These tools provide administrative capabilities for managing users, organizations, and repositories. They can only be used with an access token that has admin permissions. Unauthorized access attempts will result in 403 Forbidden errors.

Security Considerations:

• Only use these tools with admin access tokens
• Admin operations are typically logged for audit purposes
• These tools can perform destructive operations (e.g., delete users)
• Ensure proper authorization and validation before use
• Consider implementing additional access controls in production environments

admin_create_user

Create a new user account (admin only).

• source_id (number, required): Authentication source ID (use 0 for local authentication)
• login_name (string, required): Login name for authentication
• username (string, required): Username for the account
• email (string, required): Email address
• password (string, required): Password for the user
• full_name (string, optional): Full name of the user
• send_notify (boolean, optional): Send notification email to user (default: false)

Example:

{
  "source_id": 0,
  "login_name": "newuser",
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "securePassword123",
  "full_name": "New User",
  "send_notify": false
}

admin_edit_user

Edit an existing user's properties (admin only).

• username (string, required): Username of the user to edit
• source_id (number, optional): Authentication source ID
• login_name (string, optional): Login name for authentication
• full_name (string, optional): Full name of the user
• email (string, optional): Email address
• password (string, optional): New password
• website (string, optional): Website URL
• location (string, optional): Location
• active (boolean, optional): Whether the account is active
• admin (boolean, optional): Whether the user is an admin
• allow_git_hook (boolean, optional): Allow git hooks
• allow_import_local (boolean, optional): Allow importing local repositories
• max_repo_creation (number, optional): Maximum number of repositories
• prohibit_login (boolean, optional): Prohibit user login
• allow_create_organization (boolean, optional): Allow creating organizations

Example:

{
  "username": "existinguser",
  "email": "newemail@example.com",
  "active": true,
  "admin": false
}

admin_delete_user

Delete a user account (admin only). This is a destructive operation.

• username (string, required): Username of the user to delete

Example:

{
  "username": "userToDelete"
}

admin_create_user_public_key

Create a public SSH key for a user (admin only).

• username (string, required): Username to add the key to
• title (string, required): Title/name for the key
• key (string, required): Public key content (SSH public key)

Example:

{
  "username": "john",
  "title": "Work Laptop",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC..."
}

admin_delete_user_public_key

Delete a public SSH key for a user (admin only).

• username (string, required): Username to remove the key from
• key_id (number, required): ID of the public key to delete

Example:

{
  "username": "john",
  "key_id": 5
}

admin_create_org

Create an organization (admin only).

• username (string, required): Organization username
• full_name (string, optional): Full name of the organization
• description (string, optional): Organization description
• website (string, optional): Organization website
• location (string, optional): Organization location

Example:

{
  "username": "engineering-team",
  "full_name": "Engineering Team",
  "description": "Core engineering organization",
  "website": "https://engineering.example.com",
  "location": "San Francisco, CA"
}

admin_list_org_teams

List all teams in an organization (admin only).

• orgname (string, required): Organization name

Example:

{
  "orgname": "engineering-team"
}

admin_create_user_org

Create an organization owned by a specific user (admin only).

• username (string, required): Username who will own the organization
• org_username (string, required): Organization username
• full_name (string, optional): Full name of the organization
• description (string, optional): Organization description
• website (string, optional): Organization website
• location (string, optional): Organization location

Example:

{
  "username": "john",
  "org_username": "johns-org",
  "full_name": "John's Organization",
  "description": "Personal organization for projects"
}

admin_create_user_repo

Create a repository for a specific user (admin only).

• username (string, required): Username who will own the repository
• name (string, required): Repository name
• description (string, optional): Repository description
• private (boolean, optional): Create as private repository (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")

Example:

{
  "username": "john",
  "name": "new-project",
  "description": "A new project repository",
  "private": false,
  "auto_init": true,
  "gitignores": "Go,VisualStudioCode",
  "license": "MIT License",
  "readme": "Default"
}

Markdown Rendering Tools

These tools allow rendering markdown text to HTML without committing files, useful for previewing documentation, issue/comment content, and building custom markdown editors.

render_markdown

Render markdown text to HTML with support for GitHub Flavored Markdown (GFM) and repository context. This is the full-featured markdown rendering endpoint.

• text (string, required): Markdown text to render
• mode (string, optional): Rendering mode - either "gfm" (GitHub Flavored Markdown, default) or "markdown" (standard Markdown)
• context (string, optional): Repository context in the format "owner/repo" for repository-aware rendering (e.g., for resolving issue references like #123)

Example:

{
  "text": "# Hello World\n\nThis is **bold** and this is *italic*.\n\n- Item 1\n- Item 2\n\nSee issue #42 for details.",
  "mode": "gfm",
  "context": "myuser/myrepo"
}

Response: Returns the rendered HTML as plain text.

Use cases:

• Preview README.md before committing
• Render issue/comment markdown for display
• Generate documentation from markdown sources
• Build custom markdown editors with live preview

render_markdown_raw

Render raw markdown text to HTML using a simpler endpoint. This is a streamlined version that takes plain text input and returns HTML.

• text (string, required): Raw markdown text to render to HTML

Example:

{
  "text": "# Simple Heading\n\n**Bold text** and *italic text*."
}

Response: Returns the rendered HTML as plain text.

Use cases:

• Quick markdown previews
• Simple text-to-HTML conversion
• When you don't need repository context or mode selection

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
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

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