GitHub MCP Server

A stateless Model Context Protocol (MCP) server for the GitHub API, enabling file operations, repository management, search functionality, and more.

Features

• Stateless Architecture: Complete request isolation with no session management overhead
• Automatic Branch Creation: When creating/updating files or pushing changes, branches are automatically created if they don't exist
• Comprehensive Error Handling: Clear error messages for common issues
• Git History Preservation: Operations maintain proper Git history without force pushing
• Batch Operations: Support for both single-file and multi-file operations
• Advanced Search: Support for searching code, issues/PRs, and users
• Bearer Token Authentication: Standard Authorization header support for secure API access
• Fresh Instance Per Request: Each request gets a new server instance for complete isolation

Quick Start

Starting the Server

# Start stateless HTTP server on port 30000 (default)
node index.js

# Start HTTP server on custom port
PORT=8080 node index.js

The server provides these endpoints:

• POST /mcp - Main MCP endpoint (stateless mode)
• GET|DELETE /mcp - Disabled (returns 405 Method Not Allowed)

Authentication

All requests require a GitHub Personal Access Token via Authorization header:

Authorization: Bearer ghp_your_github_token_here

Create a GitHub Personal Access Token with repo scope.

Tools

The server provides 25 tools for comprehensive GitHub API access. Each tool requires Authorization: Bearer <token> header.

1. create_or_update_file

Create or update a single file in a repository.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "create_or_update_file",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "path": "test.txt",
        "content": "Hello World!",
        "message": "Add test file",
        "branch": "main"
      }
    }
  }'

2. search_repositories

Search for GitHub repositories.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "search_repositories",
      "arguments": {
        "query": "MCP server",
        "page": 1,
        "perPage": 10
      }
    }
  }'

3. create_repository

Create a new GitHub repository.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "create_repository",
      "arguments": {
        "name": "my-new-repo",
        "description": "A test repository",
        "private": false,
        "autoInit": true
      }
    }
  }'

4. get_file_contents

Get contents of a file or directory.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "tools/call",
    "params": {
      "name": "get_file_contents",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "path": "README.md",
        "branch": "main"
      }
    }
  }'

5. push_files

Push multiple files in a single commit.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "5",
    "method": "tools/call",
    "params": {
      "name": "push_files",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "branch": "main",
        "files": [
          {"path": "file1.txt", "content": "Content 1"},
          {"path": "file2.txt", "content": "Content 2"}
        ],
        "message": "Add multiple files"
      }
    }
  }'

6. create_issue

Create a new issue.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "6",
    "method": "tools/call",
    "params": {
      "name": "create_issue",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "title": "Bug found",
        "body": "There is a bug in the code",
        "labels": ["bug"],
        "assignees": ["octocat"]
      }
    }
  }'

7. create_pull_request

Create a new pull request.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "7",
    "method": "tools/call",
    "params": {
      "name": "create_pull_request",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "title": "Add new feature",
        "body": "This PR adds a new feature",
        "head": "feature-branch",
        "base": "main",
        "draft": false
      }
    }
  }'

8. fork_repository

Fork a repository.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "8",
    "method": "tools/call",
    "params": {
      "name": "fork_repository",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World"
      }
    }
  }'

9. create_branch

Create a new branch.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "9",
    "method": "tools/call",
    "params": {
      "name": "create_branch",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "branch": "new-feature",
        "from_branch": "main"
      }
    }
  }'

10. list_commits

Get list of commits from a branch.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "10",
    "method": "tools/call",
    "params": {
      "name": "list_commits",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "sha": "main",
        "page": 1,
        "perPage": 10
      }
    }
  }'

11. list_issues

List and filter repository issues.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "11",
    "method": "tools/call",
    "params": {
      "name": "list_issues",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "state": "open",
        "labels": ["bug"],
        "sort": "created",
        "direction": "desc"
      }
    }
  }'

12. update_issue

Update an existing issue.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "12",
    "method": "tools/call",
    "params": {
      "name": "update_issue",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "issue_number": 1,
        "title": "Updated issue title",
        "state": "closed",
        "labels": ["resolved"]
      }
    }
  }'

13. add_issue_comment

Add a comment to an issue.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "13",
    "method": "tools/call",
    "params": {
      "name": "add_issue_comment",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "issue_number": 1,
        "body": "This is a comment on the issue"
      }
    }
  }'

14. search_code

Search for code across GitHub repositories.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "14",
    "method": "tools/call",
    "params": {
      "name": "search_code",
      "arguments": {
        "q": "import express language:typescript",
        "sort": "indexed",
        "order": "desc",
        "per_page": 10
      }
    }
  }'

15. search_issues

Search for issues and pull requests.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "15",
    "method": "tools/call",
    "params": {
      "name": "search_issues",
      "arguments": {
        "q": "memory leak is:issue is:open label:bug",
        "sort": "created",
        "order": "desc",
        "per_page": 10
      }
    }
  }'

16. search_users

Search for GitHub users.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "16",
    "method": "tools/call",
    "params": {
      "name": "search_users",
      "arguments": {
        "q": "fullstack developer location:London followers:>100",
        "sort": "followers",
        "order": "desc",
        "per_page": 10
      }
    }
  }'

17. get_issue

Get details of a specific issue.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "17",
    "method": "tools/call",
    "params": {
      "name": "get_issue",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "issue_number": 1
      }
    }
  }'

18. get_pull_request

Get details of a specific pull request.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "18",
    "method": "tools/call",
    "params": {
      "name": "get_pull_request",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "pull_number": 1
      }
    }
  }'

19. list_pull_requests

List and filter repository pull requests.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "19",
    "method": "tools/call",
    "params": {
      "name": "list_pull_requests",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "state": "open",
        "base": "main",
        "sort": "created",
        "direction": "desc"
      }
    }
  }'

20. create_pull_request_review

Create a review on a pull request.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "20",
    "method": "tools/call",
    "params": {
      "name": "create_pull_request_review",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "pull_number": 1,
        "body": "Looks good to me!",
        "event": "APPROVE"
      }
    }
  }'

21. merge_pull_request

Merge a pull request.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "21",
    "method": "tools/call",
    "params": {
      "name": "merge_pull_request",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "pull_number": 1,
        "commit_title": "Merge feature branch",
        "merge_method": "merge"
      }
    }
  }'

22. get_pull_request_files

Get the list of files changed in a pull request.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "22",
    "method": "tools/call",
    "params": {
      "name": "get_pull_request_files",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "pull_number": 1
      }
    }
  }'

23. get_pull_request_status

Get the combined status of all status checks for a pull request.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "23",
    "method": "tools/call",
    "params": {
      "name": "get_pull_request_status",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "pull_number": 1
      }
    }
  }'

24. update_pull_request_branch

Update a pull request branch with the latest changes from the base branch.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "24",
    "method": "tools/call",
    "params": {
      "name": "update_pull_request_branch",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "pull_number": 1
      }
    }
  }'

25. get_pull_request_comments

Get the review comments on a pull request.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "25",
    "method": "tools/call",
    "params": {
      "name": "get_pull_request_comments",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "pull_number": 1
      }
    }
  }'

26. get_pull_request_reviews

Get the reviews on a pull request.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "26",
    "method": "tools/call",
    "params": {
      "name": "get_pull_request_reviews",
      "arguments": {
        "owner": "octocat",
        "repo": "Hello-World",
        "pull_number": 1
      }
    }
  }'

List Available Tools

Get the complete list of available tools:

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ghp_your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tools-list",
    "method": "tools/list",
    "params": {}
  }'

Authentication Setup

Personal Access Token

Create a GitHub Personal Access Token with appropriate permissions:

• Go to Personal access tokens
• Create a token with the repo scope ("Full control of private repositories")
• For public repositories only, use the public_repo scope

Usage with Claude Desktop

Docker

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "mcp/github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

NPX

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Build

Docker build:

docker build -t mcp/github -f github/Dockerfile .

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.