{"slug": "building-a-python-mcp-server-from-scratch-a-practical-github-api-guide", "title": "Building a Python MCP Server from Scratch - A Practical GitHub API Guide", "summary": "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.", "body_md": "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.\n\nThis 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.\n\nPrerequisites: Python 3.10+, uv or pip, and Claude Desktop or Claude Code installed.\n\nMCP 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.\n\nEvery 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.\n\nFor 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.\n\nCreate a fresh directory and install the MCP SDK with the `[cli]`\n\nextra, which includes the dev server and inspector launcher:\n\n```\nmkdir github-mcp-server\ncd github-mcp-server\nuv init .\nuv add \"mcp[cli]\" httpx\n```\n\nIf you prefer pip, run `pip install \"mcp[cli]\" httpx`\n\ninstead. Your project needs just three files: `server.py`\n\n, `pyproject.toml`\n\n(if using uv), and an optional `.env`\n\nfor your GitHub token.\n\nBefore 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:\n\n``` python\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"hello-mcp\")\n\n@mcp.tool()\ndef greet(name: str) -> str:\n    \"\"\"Return a personalized greeting. Use this when asked to greet someone.\"\"\"\n    return f\"Hello, {name}! Your MCP server is working.\"\n\nif __name__ == \"__main__\":\n    mcp.run(transport=\"stdio\")\n```\n\nRun `uv run mcp dev server.py`\n\nto launch the MCP Inspector at `http://localhost:5173`\n\n. Navigate to the Tools tab, call `greet`\n\nwith any name, and confirm the response. Three things matter here: `FastMCP`\n\nhandles all JSON-RPC plumbing, the `@mcp.tool()`\n\ndecorator 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.\n\nNow 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.\n\n``` python\nimport os, logging, sys, httpx\nfrom pydantic import BaseModel\nfrom mcp.server.fastmcp import FastMCP\n\nlogging.basicConfig(stream=sys.stderr, level=logging.INFO)\nlogger = logging.getLogger(__name__)\n\nmcp = FastMCP(\n    \"github-tools\",\n    instructions=(\n        \"This server provides tools to interact with the GitHub API. \"\n        \"Use get_repo_info to fetch repository metadata. \"\n        \"Use list_open_issues to retrieve open issues for a repository.\"\n    ),\n)\n\nGITHUB_TOKEN = os.environ.get(\"GITHUB_TOKEN\", \"\")\n\ndef _github_headers() -> dict[str, str]:\n    headers = {\n        \"Accept\": \"application/vnd.github+json\",\n        \"X-GitHub-Api-Version\": \"2022-11-28\",\n    }\n    if GITHUB_TOKEN:\n        headers[\"Authorization\"] = f\"Bearer {GITHUB_TOKEN}\"\n    return headers\n\nclass RepoInfo(BaseModel):\n    full_name: str\n    description: str | None\n    stars: int\n    forks: int\n    open_issues: int\n    language: str | None\n    url: str\n\n@mcp.tool()\nasync def get_repo_info(owner: str, repo: str) -> RepoInfo:\n    \"\"\"\n    Fetch metadata for a GitHub repository including stars, forks, and open issue count.\n    Args:\n        owner: GitHub username or organization (e.g. 'anthropics')\n        repo: Repository name (e.g. 'claude-code')\n    \"\"\"\n    async with httpx.AsyncClient() as client:\n        response = await client.get(\n            f\"https://api.github.com/repos/{owner}/{repo}\",\n            headers=_github_headers(),\n            timeout=10.0,\n        )\n        response.raise_for_status()\n    data = response.json()\n    return RepoInfo(\n        full_name=data[\"full_name\"],\n        description=data.get(\"description\"),\n        stars=data[\"stargazers_count\"],\n        forks=data[\"forks_count\"],\n        open_issues=data[\"open_issues_count\"],\n        language=data.get(\"language\"),\n        url=data[\"html_url\"],\n    )\n\n@mcp.tool()\nasync def list_open_issues(owner: str, repo: str, limit: int = 10) -> str:\n    \"\"\"\n    List open issues for a GitHub repository, ordered by most recently updated.\n    Args:\n        owner: GitHub username or organization\n        repo: Repository name\n        limit: Max issues to return (1-30, default 10)\n    \"\"\"\n    limit = max(1, min(limit, 30))\n    async with httpx.AsyncClient() as client:\n        response = await client.get(\n            f\"https://api.github.com/repos/{owner}/{repo}/issues\",\n            headers=_github_headers(),\n            params={\"state\": \"open\", \"per_page\": limit, \"sort\": \"updated\"},\n            timeout=10.0,\n        )\n        response.raise_for_status()\n    issues = response.json()\n    if not issues:\n        return f\"No open issues found for {owner}/{repo}.\"\n    lines = [f\"Open issues in **{owner}/{repo}** (showing {len(issues)}):\\n\"]\n    for issue in issues:\n        lines.append(f\"- #{issue['number']}: {issue['title']}\")\n    return \"\\n\".join(lines)\n\nif __name__ == \"__main__\":\n    mcp.run(transport=\"stdio\")\n```\n\nA 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`\n\n- the AI will occasionally send `0`\n\n, `100`\n\n, or a string.\n\nResources 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:\n\n``` php\n@mcp.resource(\"config://github-tools/status\")\ndef server_status() -> str:\n    \"\"\"Report whether the server has a GitHub token configured.\"\"\"\n    auth_status = \"authenticated\" if GITHUB_TOKEN else \"unauthenticated (rate-limited to 60 req/hr)\"\n    return f\"GitHub Tools MCP Server\\nStatus: {auth_status}\"\n\n@mcp.resource(\"github://repos/{owner}/{repo}/readme\")\nasync def get_readme(owner: str, repo: str) -> str:\n    \"\"\"Fetch the raw README content for a repository.\"\"\"\n    async with httpx.AsyncClient() as client:\n        response = await client.get(\n            f\"https://api.github.com/repos/{owner}/{repo}/readme\",\n            headers={**_github_headers(), \"Accept\": \"application/vnd.github.raw+json\"},\n            timeout=10.0,\n        )\n        if response.status_code == 404:\n            return \"No README found for this repository.\"\n        response.raise_for_status()\n        return response.text\n```\n\nPrompts are stored instruction templates any MCP client can call by name. This one structures a code review request around the GitHub tools we defined:\n\n``` php\n@mcp.prompt()\ndef review_pull_request(owner: str, repo: str, pr_number: int) -> str:\n    \"\"\"Prompt template for reviewing a GitHub pull request.\"\"\"\n    return (\n        f\"Please review pull request #{pr_number} in {owner}/{repo}. \"\n        f\"Start by fetching the repository info with get_repo_info, \"\n        f\"then list the open issues to understand the project context. \"\n        f\"Focus your review on correctness, performance, and adherence to the project's patterns.\"\n    )\n```\n\nThe fastest way to validate your server is with the built-in inspector - no Claude required. Run `uv run mcp dev server.py`\n\nand open `http://localhost:5173`\n\n.\n\nSet your `GITHUB_TOKEN`\n\nin 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.\n\nOpen the Claude Desktop config file - on macOS at `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n, on Windows at `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n. Add your server under `mcpServers`\n\n:\n\n```\n{\n  \"mcpServers\": {\n    \"github-tools\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\", \"--with\", \"mcp[cli]\", \"--with\", \"httpx\",\n        \"python\", \"/absolute/path/to/github-mcp-server/server.py\"\n      ],\n      \"env\": {\n        \"PYTHONUNBUFFERED\": \"1\",\n        \"GITHUB_TOKEN\": \"your_github_token_here\"\n      }\n    }\n  }\n}\n```\n\nUse `uv run`\n\nrather than a bare `python`\n\ncommand - Claude Desktop spawns its own shell environment without your PATH, so bare `python`\n\nwill often fail. Fully quit and restart Claude Desktop after saving. A plug icon in the input box confirms the server connected.\n\nFor Claude Code, use the `claude mcp add`\n\nCLI command. The `--`\n\nseparator is required to separate the server name from the launch command:\n\n```\nclaude mcp add github-tools \\\n  -e GITHUB_TOKEN=your_token \\\n  -e PYTHONUNBUFFERED=1 \\\n  -- uv run --with \"mcp[cli]\" --with httpx python /absolute/path/to/server.py\n```\n\nTo share the server config with your team, use `--scope project`\n\n. This writes an `.mcp.json`\n\nfile to the repository root and prompts team members to activate it when they open the project. Run `claude mcp list`\n\nto confirm registration.", "url": "https://wpnews.pro/news/building-a-python-mcp-server-from-scratch-a-practical-github-api-guide", "canonical_source": "https://dev.to/moksh/building-a-python-mcp-server-from-scratch-a-practical-github-api-guide-397k", "published_at": "2026-06-19 08:53:46+00:00", "updated_at": "2026-06-19 09:07:21.491992+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models", "ai-tools", "ai-agents"], "entities": ["Anthropic", "Linux Foundation", "GitHub", "Claude Desktop", "Claude Code", "FastMCP", "httpx", "MCP Inspector"], "alternates": {"html": "https://wpnews.pro/news/building-a-python-mcp-server-from-scratch-a-practical-github-api-guide", "markdown": "https://wpnews.pro/news/building-a-python-mcp-server-from-scratch-a-practical-github-api-guide.md", "text": "https://wpnews.pro/news/building-a-python-mcp-server-from-scratch-a-practical-github-api-guide.txt", "jsonld": "https://wpnews.pro/news/building-a-python-mcp-server-from-scratch-a-practical-github-api-guide.jsonld"}}