Building a Python MCP Server from Scratch - A Practical GitHub API Guide

A developer built a Python MCP server from scratch that integrates with the GitHub API, demonstrating how to define tools, resources, and prompts using the Model Context Protocol. The server, which can be tested with the MCP Inspector and wired into Claude Desktop or Claude Code, provides a practical starting point for adding live external data to AI assistants. The project uses the FastMCP library and httpx for GitHub API calls, with support for stdio transport.

The Model Context Protocol has gone from a niche Anthropic project to industry-standard infrastructure in under two years - hitting 97 million monthly SDK downloads and earning a permanent home under the Linux Foundation. Every major AI coding tool now speaks MCP natively, yet most tutorials either list pre-built servers to install or recite the spec without building anything real. This guide walks you through writing a Python MCP server from zero: defining tools, resources, and prompts, testing with the MCP Inspector, and wiring it into Claude Desktop or Claude Code. The working example targets the GitHub API - a practical starting point you can extend for any project that needs live external data inside an AI assistant. Prerequisites: Python 3.10+, uv or pip, and Claude Desktop or Claude Code installed. MCP is a JSON-RPC protocol that gives an AI client a standardized way to call external services. The client - Claude, Cursor, or any compliant tool - sends a request and your server handles it, regardless of what language it is written in. Every MCP server exposes three core primitives. Tools are callable functions the AI can invoke to take action or fetch data. Resources are read-only data endpoints the AI can pull from - similar to files or database records. Prompts are reusable instruction templates stored on the server and referenced by name, useful for standardizing workflows across a team. For transport, this guide uses stdio - the server runs as a subprocess and communicates over stdin/stdout. This works out of the box with Claude Desktop and Claude Code. For production or remote deployments, Streamable HTTP is the alternative. Create a fresh directory and install the MCP SDK with the cli extra, which includes the dev server and inspector launcher: mkdir github-mcp-server cd github-mcp-server uv init . uv add "mcp cli " httpx If you prefer pip, run pip install "mcp cli " httpx instead. Your project needs just three files: server.py , pyproject.toml if using uv , and an optional .env for your GitHub token. Before diving into the full server, start with the simplest possible working example. This lets you confirm the SDK is wired up correctly before adding any real logic: python from mcp.server.fastmcp import FastMCP mcp = FastMCP "hello-mcp" @mcp.tool def greet name: str - str: """Return a personalized greeting. Use this when asked to greet someone.""" return f"Hello, {name} Your MCP server is working." if name == " main ": mcp.run transport="stdio" Run uv run mcp dev server.py to launch the MCP Inspector at http://localhost:5173 . Navigate to the Tools tab, call greet with any name, and confirm the response. Three things matter here: FastMCP handles all JSON-RPC plumbing, the @mcp.tool decorator auto-generates a schema from your type hints, and the docstring is what the AI reads to decide whether to call this tool - write it clearly. Now replace that minimal example with a real server. This version exposes two tools: one that fetches repository metadata and one that lists open issues, both backed by live GitHub API calls via httpx. python import os, logging, sys, httpx from pydantic import BaseModel from mcp.server.fastmcp import FastMCP logging.basicConfig stream=sys.stderr, level=logging.INFO logger = logging.getLogger name mcp = FastMCP "github-tools", instructions= "This server provides tools to interact with the GitHub API. " "Use get repo info to fetch repository metadata. " "Use list open issues to retrieve open issues for a repository." , GITHUB TOKEN = os.environ.get "GITHUB TOKEN", "" def github headers - dict str, str : headers = { "Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28", } if GITHUB TOKEN: headers "Authorization" = f"Bearer {GITHUB TOKEN}" return headers class RepoInfo BaseModel : full name: str description: str | None stars: int forks: int open issues: int language: str | None url: str @mcp.tool async def get repo info owner: str, repo: str - RepoInfo: """ Fetch metadata for a GitHub repository including stars, forks, and open issue count. Args: owner: GitHub username or organization e.g. 'anthropics' repo: Repository name e.g. 'claude-code' """ async with httpx.AsyncClient as client: response = await client.get f"https://api.github.com/repos/{owner}/{repo}", headers= github headers , timeout=10.0, response.raise for status data = response.json return RepoInfo full name=data "full name" , description=data.get "description" , stars=data "stargazers count" , forks=data "forks count" , open issues=data "open issues count" , language=data.get "language" , url=data "html url" , @mcp.tool async def list open issues owner: str, repo: str, limit: int = 10 - str: """ List open issues for a GitHub repository, ordered by most recently updated. Args: owner: GitHub username or organization repo: Repository name limit: Max issues to return 1-30, default 10 """ limit = max 1, min limit, 30 async with httpx.AsyncClient as client: response = await client.get f"https://api.github.com/repos/{owner}/{repo}/issues", headers= github headers , params={"state": "open", "per page": limit, "sort": "updated"}, timeout=10.0, response.raise for status issues = response.json if not issues: return f"No open issues found for {owner}/{repo}." lines = f"Open issues in {owner}/{repo} showing {len issues } :\n" for issue in issues: lines.append f"- {issue 'number' }: {issue 'title' }" return "\n".join lines if name == " main ": mcp.run transport="stdio" A few deliberate design choices are worth noting. Returning a Pydantic model from a tool gives the AI a typed, structured response it can reference field by field - far more reliable than parsing a formatted string. For string-return tools, catching exceptions and returning an error message is safer than letting them propagate, since an unhandled exception under stdio can kill the entire connection. Always clamp numeric inputs like limit - the AI will occasionally send 0 , 100 , or a string. Resources let the AI read data passively. Here is one that reports whether a GitHub token is configured, and a dynamic one that fetches a repo's README: php @mcp.resource "config://github-tools/status" def server status - str: """Report whether the server has a GitHub token configured.""" auth status = "authenticated" if GITHUB TOKEN else "unauthenticated rate-limited to 60 req/hr " return f"GitHub Tools MCP Server\nStatus: {auth status}" @mcp.resource "github://repos/{owner}/{repo}/readme" async def get readme owner: str, repo: str - str: """Fetch the raw README content for a repository.""" async with httpx.AsyncClient as client: response = await client.get f"https://api.github.com/repos/{owner}/{repo}/readme", headers={ github headers , "Accept": "application/vnd.github.raw+json"}, timeout=10.0, if response.status code == 404: return "No README found for this repository." response.raise for status return response.text Prompts are stored instruction templates any MCP client can call by name. This one structures a code review request around the GitHub tools we defined: php @mcp.prompt def review pull request owner: str, repo: str, pr number: int - str: """Prompt template for reviewing a GitHub pull request.""" return f"Please review pull request {pr number} in {owner}/{repo}. " f"Start by fetching the repository info with get repo info, " f"then list the open issues to understand the project context. " f"Focus your review on correctness, performance, and adherence to the project's patterns." The fastest way to validate your server is with the built-in inspector - no Claude required. Run uv run mcp dev server.py and open http://localhost:5173 . Set your GITHUB TOKEN in the Environment Variables section before connecting. Then test tools in the Tools tab, verify resources in the Resources tab, and confirm prompts show up in the Prompts tab. If anything fails, the Logs panel shows the raw JSON-RPC exchange, which is the most direct way to pinpoint the issue. Open the Claude Desktop config file - on macOS at ~/Library/Application Support/Claude/claude desktop config.json , on Windows at %APPDATA%\Claude\claude desktop config.json . Add your server under mcpServers : { "mcpServers": { "github-tools": { "command": "uv", "args": "run", "--with", "mcp cli ", "--with", "httpx", "python", "/absolute/path/to/github-mcp-server/server.py" , "env": { "PYTHONUNBUFFERED": "1", "GITHUB TOKEN": "your github token here" } } } } Use uv run rather than a bare python command - Claude Desktop spawns its own shell environment without your PATH, so bare python will often fail. Fully quit and restart Claude Desktop after saving. A plug icon in the input box confirms the server connected. For Claude Code, use the claude mcp add CLI command. The -- separator is required to separate the server name from the launch command: claude mcp add github-tools \ -e GITHUB TOKEN=your token \ -e PYTHONUNBUFFERED=1 \ -- uv run --with "mcp cli " --with httpx python /absolute/path/to/server.py To share the server config with your team, use --scope project . This writes an .mcp.json file to the repository root and prompts team members to activate it when they open the project. Run claude mcp list to confirm registration.