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

Installation

Prerequisites

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

Setup

1. Clone this repository:

   git clone <repository-url>
   cd gogs-mcp-server
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

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

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

Usage

With Claude Desktop

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

With Other MCP Clients

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

# Run the server
npm start

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)

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)

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