gogs-mcp/SERVICE.md

Systemd Service Setup

This directory contains files for running the Gogs MCP Server as a systemd service on Linux.

Files

• gogs-mcp-server.service: Systemd service configuration
• install-service.sh: Installation script
• uninstall-service.sh: Uninstallation script

Configuration

The service is configured to run on port 3100 (instead of the default 3000) with HTTP transport.

Installation

1. Configure the Service

Before installing, edit gogs-mcp-server.service to set your Gogs server details:

nano gogs-mcp-server.service

Update these environment variables:

• GOGS_SERVER_URL: Your Gogs server URL (e.g., https://gogs.example.com)
• GOGS_ACCESS_TOKEN: Your Gogs access token

2. Run the Installation Script

sudo ./install-service.sh

This will:

• Copy the service file to /etc/systemd/system/
• Reload systemd daemon
• Enable the service to start on boot

3. Start the Service

sudo systemctl start gogs-mcp-server

4. Check Status

sudo systemctl status gogs-mcp-server

Usage

Service Commands

# Start the service
sudo systemctl start gogs-mcp-server

# Stop the service
sudo systemctl stop gogs-mcp-server

# Restart the service
sudo systemctl restart gogs-mcp-server

# Check status
sudo systemctl status gogs-mcp-server

# Enable on boot
sudo systemctl enable gogs-mcp-server

# Disable on boot
sudo systemctl disable gogs-mcp-server

View Logs

# Follow live logs
sudo journalctl -u gogs-mcp-server -f

# View recent logs
sudo journalctl -u gogs-mcp-server -n 50

# View logs since last boot
sudo journalctl -u gogs-mcp-server -b

Testing the Server

Once the service is running, test it:

# Health check
curl http://localhost:3100/health

# Expected response:
# {"status":"ok","service":"gogs-mcp-server","transport":"http"}

# Test SSE endpoint
curl -N http://localhost:3100/sse

Claude Code Integration

From inside your Claude Code Docker container, add the MCP server:

# Docker Desktop (Mac/Windows)
claude mcp add --transport sse gogs http://host.docker.internal:3100/sse

# Linux Docker (using docker0 bridge)
claude mcp add --transport sse gogs http://172.17.0.1:3100/sse

# Or use host machine IP
claude mcp add --transport sse gogs http://<host-ip>:3100/sse

Verify it was added:

claude mcp list

Updating Configuration

If you need to change environment variables after installation:

# Edit the service file
sudo nano /etc/systemd/system/gogs-mcp-server.service

# Reload systemd configuration
sudo systemctl daemon-reload

# Restart the service
sudo systemctl restart gogs-mcp-server

Uninstallation

To remove the service:

sudo ./uninstall-service.sh

This will:

• Stop the service
• Disable it from starting on boot
• Remove the service file
• Reload systemd daemon

Troubleshooting

Service won't start

Check the logs for errors:

sudo journalctl -u gogs-mcp-server -n 50

Common issues:

• Incorrect GOGS_SERVER_URL or GOGS_ACCESS_TOKEN
• Port 3100 already in use
• Node.js not installed or wrong path
• Project not built (run npm run build first)

Port already in use

Check what's using port 3100:

sudo lsof -i :3100

Change the port in the service file if needed:

sudo nano /etc/systemd/system/gogs-mcp-server.service
# Change HTTP_PORT=3100 to another port
sudo systemctl daemon-reload
sudo systemctl restart gogs-mcp-server

Can't connect from Docker container

1. Verify service is running:

   sudo systemctl status gogs-mcp-server
   curl http://localhost:3100/health
   

2. Check firewall settings:

   sudo ufw status
   sudo ufw allow 3100/tcp
   

3. Verify Docker can reach host:

   # From inside container
   curl http://172.17.0.1:3100/health
   

Security Notes

The service includes these security settings:

• NoNewPrivileges=true: Prevents privilege escalation
• PrivateTmp=true: Uses private /tmp directory

For production deployments, consider:

• Using environment file instead of inline environment variables
• Setting up SSL/TLS reverse proxy (nginx, caddy)
• Restricting network access with firewall rules
• Running on a non-standard port or behind authentication

Environment File Alternative

Instead of inline environment variables, you can use an environment file:

1. Create /etc/gogs-mcp-server.env:

   GOGS_SERVER_URL=https://gogs.example.com
   GOGS_ACCESS_TOKEN=your-token-here
   TRANSPORT_MODE=http
   HTTP_PORT=3100
   HTTP_HOST=0.0.0.0
   NODE_ENV=production
   

2. Update service file:

   [Service]
   EnvironmentFile=/etc/gogs-mcp-server.env
   

3. Secure the file:

   sudo chmod 600 /etc/gogs-mcp-server.env
   sudo chown root:root /etc/gogs-mcp-server.env