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

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.

What an MCP Server Actually Does

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.

Setting Up the Project

Create a fresh directory and install the MCP SDK with the [cli] extra, which includes the dev server and inspector launcher. 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.

A Minimal Tool in 10 Lines

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. The FastMCP class 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. Run uv run mcp dev server.py to launch the MCP Inspector at http://localhost:5173 and test it from the Tools tab.

Building the GitHub Tools Server

This version of the server exposes two tools: one that fetches repository metadata and one that lists open issues, both backed by live GitHub API calls via httpx. Returning a Pydantic model from a tool gives the AI a typed, structured response - 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 - the AI will occasionally send unexpected values.

Adding Resources and Prompts

Resources let the AI read data passively - like checking whether a GitHub token is configured or fetching a repo's README. They use URI templates and return data without side effects, making them ideal for read-only lookups. Prompts are stored instruction templates any MCP client can call by name. A well-crafted prompt template standardizes how the AI uses your tools across different sessions and team members, and can significantly improve output quality by guiding the model toward the right sequence of tool calls.

Testing with the MCP Inspector

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.

Connecting to Claude Desktop

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 using 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.

Connecting to Claude Code

For Claude Code, use the claude mcp add CLI command. The -- separator is required to separate the server name from the launch command. 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.