Build a Custom MCP Server: Python and TypeScript Tutorial

┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│                  │         │                  │         │                  │
│   AI Host        │  MCP    │   MCP Server     │  HTTP   │   External API   │
│   (Claude/       │◄───────►│   (Your Code)    │◄───────►│   (GitHub, DB,   │
│    Cursor)       │         │                  │         │    custom API)   │
│                  │         │                  │         │                  │
└──────────────────┘         └──────────────────┘         └──────────────────┘

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create and set up the project
uv init github-stars-mcp
cd github-stars-mcp
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]" httpx

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# Initialize the MCP server
mcp = FastMCP("github-stars")

GITHUB_API = "https://api.github.com"


async def fetch_repo(owner: str, repo: str) -> dict[str, Any] | None:
    """Fetch repository data from GitHub API."""
    headers = {
        "Accept": "application/vnd.github.v3+json",
        "User-Agent": "mcp-github-stars/1.0",
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(
                f"{GITHUB_API}/repos/{owner}/{repo}",
                headers=headers,
                timeout=10.0,
            )
            response.raise_for_status()
            return response.json()
        except httpx.HTTPError:
            return None


@mcp.tool()
async def get_repo_stars(owner: str, repo: str) -> str:
    """Get the star count and key stats for a GitHub repository.

    Args:
        owner: GitHub username or organization (e.g. 'anthropics')
        repo: Repository name (e.g. 'claude-code')
    """
    data = await fetch_repo(owner, repo)
    if not data:
        return f"Could not fetch data for {owner}/{repo}. Check the name and try again."

    return f"""Repository: {data['full_name']}
Stars: {data['stargazers_count']:,}
Forks: {data['forks_count']:,}
Open Issues: {data['open_issues_count']:,}
Language: {data.get('language', 'Not specified')}
Description: {data.get('description', 'No description')}
Last Updated: {data['updated_at'][:10]}"""


@mcp.tool()
async def compare_repos(repos: list[str]) -> str:
    """Compare star counts across multiple GitHub repositories.

    Args:
        repos: List of repos in 'owner/repo' format (e.g. ['facebook/react', 'vuejs/vue'])
    """
    results = []
    for repo_str in repos:
        parts = repo_str.split("/")
        if len(parts) != 2:
            results.append({"name": repo_str, "error": "Invalid format. Use owner/repo"})
            continue

        data = await fetch_repo(parts[0], parts[1])
        if data:
            results.append({
                "name": data["full_name"],
                "stars": data["stargazers_count"],
                "forks": data["forks_count"],
                "language": data.get("language", "N/A"),
            })
        else:
            results.append({"name": repo_str, "error": "Not found"})

    # Sort by stars descending
    valid = [r for r in results if "stars" in r]
    errors = [r for r in results if "error" in r]
    valid.sort(key=lambda x: x["stars"], reverse=True)

    output = "Repository Comparison (sorted by stars):\n\n"
    for i, r in enumerate(valid, 1):
        medal = ["🥇", "🥈", "🥉"][i - 1] if i <= 3 else f"{i}."
        output += f"{medal} {r['name']}: {r['stars']:,} stars | {r['forks']:,} forks | {r['language']}\n"

    if errors:
        output += "\nErrors:\n"
        for r in errors:
            output += f"  - {r['name']}: {r['error']}\n"

    return output


def main():
    mcp.run(transport="stdio")


if __name__ == "__main__":
    main()

# The MCP Inspector opens a web UI for testing your server
uv run mcp dev server.py

# macOS
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
code %AppData%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github-stars": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/github-stars-mcp",
        "run", "server.py"
      ]
    }
  }
}

mkdir github-stars-mcp
cd github-stars-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod@3
npm install -D @types/node typescript
mkdir src

{
  "type": "module",
  "bin": {
    "github-stars": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && chmod 755 build/index.js"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const GITHUB_API = "https://api.github.com";

const server = new McpServer({
  name: "github-stars",
  version: "1.0.0",
});

async function fetchRepo(owner: string, repo: string): Promise<any | null> {
  try {
    const response = await fetch(`${GITHUB_API}/repos/${owner}/${repo}`, {
      headers: {
        "Accept": "application/vnd.github.v3+json",
        "User-Agent": "mcp-github-stars/1.0",
      },
    });
    if (!response.ok) return null;
    return await response.json();
  } catch {
    return null;
  }
}

// Tool: Get stars for a single repo
server.tool(
  "get_repo_stars",
  {
    owner: z.string().describe("GitHub username or org (e.g. 'anthropics')"),
    repo: z.string().describe("Repository name (e.g. 'claude-code')"),
  },
  async ({ owner, repo }) => {
    const data = await fetchRepo(owner, repo);
    if (!data) {
      return {
        content: [{
          type: "text" as const,
          text: `Could not fetch data for ${owner}/${repo}.`,
        }],
      };
    }
    return {
      content: [{
        type: "text" as const,
        text: [
          `Repository: ${data.full_name}`,
          `Stars: ${data.stargazers_count.toLocaleString()}`,
          `Forks: ${data.forks_count.toLocaleString()}`,
          `Open Issues: ${data.open_issues_count.toLocaleString()}`,
          `Language: ${data.language ?? "Not specified"}`,
          `Description: ${data.description ?? "No description"}`,
          `Last Updated: ${data.updated_at.slice(0, 10)}`,
        ].join("\n"),
      }],
    };
  }
);

// Tool: Compare multiple repos
server.tool(
  "compare_repos",
  {
    repos: z.array(z.string()).describe("Repos in 'owner/repo' format"),
  },
  async ({ repos }) => {
    const results: Array<{ name: string; stars?: number; forks?: number; language?: string; error?: string }> = [];

    for (const repoStr of repos) {
      const [owner, repo] = repoStr.split("/");
      if (!owner || !repo) {
        results.push({ name: repoStr, error: "Invalid format" });
        continue;
      }
      const data = await fetchRepo(owner, repo);
      if (data) {
        results.push({
          name: data.full_name,
          stars: data.stargazers_count,
          forks: data.forks_count,
          language: data.language ?? "N/A",
        });
      } else {
        results.push({ name: repoStr, error: "Not found" });
      }
    }

    const valid = results.filter((r) => r.stars !== undefined);
    valid.sort((a, b) => (b.stars ?? 0) - (a.stars ?? 0));
    const medals = ["🥇", "🥈", "🥉"];

    let output = "Repository Comparison (sorted by stars):\n\n";
    valid.forEach((r, i) => {
      const prefix = i < 3 ? medals[i] : `${i + 1}.`;
      output += `${prefix} ${r.name}: ${r.stars!.toLocaleString()} stars | ${r.forks!.toLocaleString()} forks | ${r.language}\n`;
    });

    return { content: [{ type: "text" as const, text: output }] };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main();

npm run build
npx @modelcontextprotocol/inspector node build/index.js

{
  "mcpServers": {
    "github-stars": {
      "command": "node",
      "args": ["/absolute/path/to/github-stars-mcp/build/index.js"]
    }
  }
}

@mcp.resource("github://profile/{username}")
async def get_profile(username: str) -> str:
    """Fetch a GitHub user's profile information."""
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"{GITHUB_API}/users/{username}",
            headers={"User-Agent": "mcp-github-stars/1.0"},
        )
        if response.status_code != 200:
            return f"User {username} not found."
        data = response.json()
        return f"""Name: {data.get('name', 'N/A')}
Bio: {data.get('bio', 'N/A')}
Public Repos: {data['public_repos']}
Followers: {data['followers']}
Location: {data.get('location', 'N/A')}"""

server.resource(
  "github-profile",
  "github://profile/{username}",
  async (uri) => {
    const username = uri.pathname.split("/").pop();
    const response = await fetch(`${GITHUB_API}/users/${username}`, {
      headers: { "User-Agent": "mcp-github-stars/1.0" },
    });
    const data = await response.json();
    return {
      contents: [{
        uri: uri.href,
        mimeType: "text/plain",
        text: `Name: ${data.name}\nRepos: ${data.public_repos}\nFollowers: ${data.followers}`,
      }],
    };
  }
);

{
  "mcpServers": {
    "github-stars": {
      "command": "uv",
      "args": ["--directory", "/path/to/project", "run", "server.py"]
    }
  }
}

{
  "mcpServers": {
    "github-stars": {
      "command": "uv",
      "args": ["--directory", "/path/to/project", "run", "server.py"]
    }
  }
}

{
  "mcpServers": {
    "github-stars": {
      "command": "uv",
      "args": ["--directory", "/path/to/project", "run", "server.py"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "github-stars": {
        "command": "uv",
        "args": ["--directory", "/path/to/project", "run", "server.py"]
      }
    }
  }
}

def main():
    # Local: mcp.run(transport="stdio")
    mcp.run(transport="sse", host="0.0.0.0", port=8080)

{
  "mcpServers": {
    "github-stars": {
      "url": "https://your-mcp-server.example.com/sse"
    }
  }
}

import os
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("github-stars")

API_KEY = os.environ.get("MCP_API_KEY")

@mcp.tool()
async def get_repo_stars(owner: str, repo: str, api_key: str) -> str:
    """Get stars for a repo. Requires valid API key."""
    if api_key != API_KEY:
        return "Invalid API key."
    # ... rest of the tool logic