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:
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.
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:
@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:
@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.