Setting Up Your Development Environment

Two Paths: TypeScript and Python

The official MCP SDKs support both TypeScript and Python. You only need to set up one, but this lesson covers both so you can choose the language you are most comfortable with — or set up both if you want to follow along with lessons in either language.

The next two lessons will each build the same first server in one language:

• Lesson 6: Your First MCP Server (TypeScript)
• Lesson 7: Your First MCP Server (Python)

Set up whichever environment matches the lesson you plan to follow.

TypeScript Setup

Prerequisites

Node.js v16 or later is required. The TypeScript MCP SDK targets ES2022 and uses Node's module resolution. To check your version:

node --version

If you need to install or upgrade Node, use the official installer at nodejs.org, or a version manager like nvm (macOS/Linux) or fnm (cross-platform).

You will also need npm (bundled with Node) and TypeScript. Install TypeScript globally if you do not already have it:

npm install -g typescript

Create the Project

mkdir my-mcp-server
cd my-mcp-server
npm init -y

Install the MCP SDK and Zod

The TypeScript SDK requires two packages: @modelcontextprotocol/sdk for the MCP implementation, and zod for input schema validation. Zod is the schema library the SDK uses to define and validate tool inputs.

npm install @modelcontextprotocol/sdk zod
npm install --save-dev typescript @types/node

Configure package.json

Open package.json and add or update these fields:

{
  "type": "module",
  "bin": {
    "my-mcp-server": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && chmod 755 build/index.js"
  },
  "files": [
    "build"
  ]
}

"type": "module" enables ES module syntax (import/export). The bin field makes your server runnable as a command after npm install, which is how Claude Desktop and Claude Code launch stdio servers.

Configure TypeScript

Create tsconfig.json in your project root:

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

The target: "ES2022" and module: "Node16" settings are required for the MCP SDK. Using older targets or CommonJS module format will cause import errors.

Create the Source Directory

mkdir src

Your server code will live in src/index.ts. The build script compiles it to build/index.js.

Verify the Setup

Create a minimal src/index.ts to verify everything compiles:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
console.error("MCP SDK imported successfully");

Run the build:

npm run build

If it succeeds without errors, your TypeScript environment is ready.

Python Setup

Prerequisites

Python 3.10 or later is required. The MCP SDK uses modern type hint syntax introduced in Python 3.10. To check your version:

python3 --version

The recommended package manager for MCP Python development is uv — a fast Python package manager that handles virtual environments automatically. Install it with:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

If you prefer not to use uv, pip with a virtual environment also works.

Create the Project

uv init my-mcp-server
cd my-mcp-server

Install the MCP SDK

The Python MCP package is mcp[cli]. The [cli] extra includes the mcp command-line tool for running and testing servers.

uv add "mcp[cli]"

If using pip instead of uv:

pip install "mcp[cli]"

The MCP SDK version 1.2.0 or later is required for FastMCP support. uv will install the current version automatically.

Verify the Setup

Create a minimal server.py to verify the SDK is importable:

from mcp.server.fastmcp import FastMCP
import sys
print("MCP SDK imported successfully", file=sys.stderr)

Run it:

uv run python server.py

If you see the confirmation message (on stderr), your Python environment is ready.

Note: the import path mcp.server.fastmcp is correct for MCP SDK 1.2.0+. Older tutorials may show different import paths — use this one.

FastMCP vs. the Low-Level SDK

The Python SDK offers two layers:

• FastMCP (high-level) — decorator-based API similar to FastAPI. Register tools with @mcp.tool(), resources with @mcp.resource(), and prompts with @mcp.prompt(). Type hints on function arguments become the input schema automatically. This is what you will use in the next lesson and for most real-world servers.
• Low-level SDK — direct access to the protocol layer for advanced use cases where you need fine-grained control over request handling. Not needed for most servers.

The FastMCP layer is built on top of the low-level SDK and covers everything in this track. Unless you are implementing a custom protocol extension or need behavior the high-level API cannot express, use FastMCP.

What You Have Now

With either setup complete, you have everything needed to write, build, and run an MCP server. The next lesson walks through building your first complete server in TypeScript — registering a real tool, connecting a transport, and testing it with Claude Desktop.