API Reference

API Reference

This document provides detailed information about the GitHub MCP Server API endpoints and tool definitions.

Base URL

All API endpoints are relative to the base URL:

http://localhost:8000

Authentication

The server uses githubauthlib for authentication, which retrieves GitHub tokens from the system keychain. No additional authentication headers are required for API requests.

Endpoints

GET /

Returns server information and available tools.

Response:

{
  "name": "github-mcp",
  "version": "0.1.0",
  "tools": [
    {
      "name": "tool_name",
      "description": "Tool description",
      "parameters": {
        "type": "object",
        "properties": {
          // Tool parameters schema
        }
      }
    }
  ]
}

POST /tool

Executes a tool call.

Request Body:

{
  "name": "tool_name",
  "parameters": {
    // Tool parameters
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "JSON-formatted response data"
    }
  ]
}

GET /sse

Server-Sent Events endpoint for streaming responses.

Response:

event: ping
data: ""

event: tool_result
data: {
  "content": [
    {
      "type": "text",
      "text": "JSON-formatted response data"
    }
  ]
}

event: error
data: "Error message"

Tool Definitions

Repository Tools

list_repositories

Lists GitHub repositories accessible to the authenticated user.

Parameters:

{
  "type": "object",
  "properties": {
    "visibility": {
      "type": "string",
      "enum": ["all", "public", "private"],
      "default": "all"
    },
    "sort": {
      "type": "string",
      "enum": ["created", "updated", "pushed", "full_name"],
      "default": "updated"
    }
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"name\": \"repo-name\", \"full_name\": \"owner/repo-name\", ...}]"
    }
  ]
}

get_repository

Gets information about a specific repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    }
  },
  "required": ["owner", "repo"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"name\": \"repo-name\", \"full_name\": \"owner/repo-name\", ...}"
    }
  ]
}

Issue Tools

list_issues

Lists issues in a repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "state": {
      "type": "string",
      "enum": ["open", "closed", "all"],
      "default": "open"
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Filter by labels"
    }
  },
  "required": ["owner", "repo"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"number\": 1, \"title\": \"Issue title\", ...}]"
    }
  ]
}

create_issue

Creates a new issue in a repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "title": {
      "type": "string",
      "description": "Issue title"
    },
    "body": {
      "type": "string",
      "description": "Issue description"
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Issue labels"
    },
    "assignees": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Issue assignees"
    }
  },
  "required": ["owner", "repo", "title"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"number\": 1, \"title\": \"Issue title\", ...}"
    }
  ]
}

Pull Request Tools

list_pull_requests

Lists pull requests in a repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "state": {
      "type": "string",
      "enum": ["open", "closed", "all"],
      "default": "open"
    },
    "sort": {
      "type": "string",
      "enum": ["created", "updated", "popularity", "long-running"],
      "default": "created"
    }
  },
  "required": ["owner", "repo"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"number\": 1, \"title\": \"PR title\", ...}]"
    }
  ]
}

create_pull_request

Creates a new pull request.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "title": {
      "type": "string",
      "description": "Pull request title"
    },
    "body": {
      "type": "string",
      "description": "Pull request description"
    },
    "head": {
      "type": "string",
      "description": "Source branch"
    },
    "base": {
      "type": "string",
      "description": "Target branch",
      "default": "main"
    },
    "draft": {
      "type": "boolean",
      "description": "Create as draft",
      "default": false
    }
  },
  "required": ["owner", "repo", "title", "head"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"number\": 1, \"title\": \"PR title\", ...}"
    }
  ]
}

Content Tools

get_file_content

Gets the content of a file in a repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "path": {
      "type": "string",
      "description": "File path"
    },
    "ref": {
      "type": "string",
      "description": "Branch/tag/commit reference"
    }
  },
  "required": ["owner", "repo", "path"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"name\": \"file.txt\", \"content\": \"file content\", ...}"
    }
  ]
}

list_directory

Lists contents of a directory in a repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "path": {
      "type": "string",
      "description": "Directory path",
      "default": ""
    },
    "ref": {
      "type": "string",
      "description": "Branch/tag/commit reference"
    }
  },
  "required": ["owner", "repo"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"name\": \"file.txt\", \"type\": \"file\", ...}]"
    }
  ]
}

Error Handling

Error Response Format

{
  "detail": "Error message"
}

Common Error Codes

• 400 Bad Request - Invalid parameters
• 401 Unauthorized - Authentication failed
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Rate Limiting

The server respects GitHub's API rate limits. Rate limit information is included in response headers:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1620000000

Best Practices

1. Error Handling

   • Always check for error responses
   • Handle rate limiting appropriately
   • Implement retry logic for transient failures

2. Performance

   • Use appropriate tool parameters
   • Cache responses when possible
   • Monitor rate limit usage

3. Security

   • Keep GitHub tokens secure
   • Use appropriate repository permissions
   • Validate all input parameters

Examples

Python

import httpx

async def call_tool(tool_name: str, parameters: dict) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/tool",
            json={
                "name": tool_name,
                "parameters": parameters
            }
        )
        response.raise_for_status()
        return response.json()

JavaScript

async function callTool(toolName, parameters) {
  const response = await fetch("http://localhost:8000/tool", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: toolName,
      parameters: parameters,
    }),
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

Related Documentation

• Getting Started - Installation and setup
• Features - Available tools
• Security - Security considerations
• Architecture - System architecture