GitHub Pages MCP Server

A Model Context Protocol (MCP) server for managing GitHub Pages deployments. This server provides tools to enable, configure, deploy, and manage GitHub Pages sites through the MCP protocol.

Features

This MCP server provides the following tools:

• enable_github_pages - Enable GitHub Pages for a repository with custom source and build settings
• get_github_pages_info - Get current GitHub Pages configuration and deployment status
• deploy_to_github_pages - Deploy files directly to GitHub Pages branch
• disable_github_pages - Disable GitHub Pages for a repository
• update_github_pages_config - Update GitHub Pages configuration (source, build type, custom domain)

Installation

npm install
npm run build

Configuration

The server requires a GitHub Personal Access Token with appropriate permissions to manage GitHub Pages.

Required GitHub Token Permissions

Your GitHub token needs the following scopes:

• `repo` (Full control of private repositories)
• `public_repo` (Access public repositories)
• `workflow` (Update GitHub Action workflows, if using workflow build type)

Setting the Token

Set the `GITHUB_TOKEN` environment variable:

export GITHUB_TOKEN=ghp_your_token_here

Usage

Running the Server

# Build and run
npm run build
node dist/index.js

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop config):

{
  "mcpServers": {
    "github-pages": {
      "command": "node",
      "args": ["/path/to/github-pages-mcp-server/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

Tools Reference

enable_github_pages

Enable GitHub Pages for a repository.

Parameters:

• `owner` (string, required): Repository owner (username or organization)
• `repo` (string, required): Repository name
• `source` (object, required):
  • `branch` (string, required): Branch to deploy from (e.g., 'main', 'gh-pages')
  • `path` (string, optional): Path to deploy from ('/' or '/docs')
• `build_type` (string, optional): Build type - 'legacy' for Jekyll or 'workflow' for GitHub Actions

Example:

{
  "owner": "username",
  "repo": "my-website",
  "source": {
    "branch": "main",
    "path": "/docs"
  },
  "build_type": "legacy"
}

get_github_pages_info

Get the current GitHub Pages configuration and status.

Parameters:

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

Example:

{
  "owner": "username",
  "repo": "my-website"
}

deploy_to_github_pages

Deploy files to a GitHub Pages branch by creating commits.

Parameters:

• `owner` (string, required): Repository owner
• `repo` (string, required): Repository name
• `branch` (string, required): Branch to deploy to (must match GitHub Pages source branch)
• `message` (string, optional): Commit message
• `files` (array, optional): Array of files to deploy
  • `path` (string, required): File path in repository
  • `content` (string, required): File content
  • `encoding` (string, optional): 'utf-8' or 'base64'

Example:

{
  "owner": "username",
  "repo": "my-website",
  "branch": "gh-pages",
  "message": "Update homepage",
  "files": [
    {
      "path": "index.html",
      "content": "Hello World",
      "encoding": "utf-8"
    }
  ]
}

disable_github_pages

Disable GitHub Pages for a repository.

Parameters:

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

Example:

{
  "owner": "username",
  "repo": "my-website"
}

update_github_pages_config

Update GitHub Pages configuration settings.

Parameters:

• `owner` (string, required): Repository owner
• `repo` (string, required): Repository name
• `source` (object, optional):
  • `branch` (string, required): Branch to deploy from
  • `path` (string, optional): Path to deploy from
• `build_type` (string, optional): 'legacy' or 'workflow'
• `cname` (string, optional): Custom domain name

Example:

{
  "owner": "username",
  "repo": "my-website",
  "source": {
    "branch": "main",
    "path": "/"
  },
  "cname": "www.example.com"
}

Development

Building

npm run build

Watching for Changes

npm run watch

Linting

npm run lint

Releasing

This project uses GitHub Actions to automatically create releases when version tags are pushed.

Creating a Release

1. Update the version in `package.json`

2. Commit the changes

3. Create and push a version tag:

git tag v1.0.0
git push origin v1.0.0

The GitHub Actions workflow will automatically:

• Build the project
• Create a GitHub release with the tag
• Upload release assets:
  • `github-pages-mcp-server-dist.tar.gz` - Compiled distribution files
  • `github-pages-mcp-server-full.tar.gz` - Full source code (excluding node_modules)
• Generate release notes automatically

Requirements

• Node.js >= 18.0.0
• GitHub Personal Access Token with repo permissions

License

MIT