Setting Up Your MCP Development Environment | Why MCP? The AI Integration Revolution

Theory is important, but now it is time to get your hands dirty. In this lesson, we will set up everything you need to build, test, and run MCP servers. By the end, you will have Python, Node.js, the FastMCP framework, and the MCP Inspector all installed and verified.

No more reading about MCP -- after this lesson, you will be ready to build.

What You Need

Here is the complete toolchain we will install:

Tool                    Purpose                         Min Version
------------------------------------------------------------------------
Python                  Primary language for MCP servers  3.10+
uv                      Fast Python package manager       0.4+
Node.js                 Running TypeScript MCP servers    18+
npm/npx                 Installing reference servers      (comes with Node)
FastMCP (Python)        High-level MCP server framework   2.0+
MCP Inspector           Web UI for testing servers        Latest
Claude Desktop          Primary MCP host for testing      Latest
Git                     Version control                   2.0+
A code editor           VS Code or Cursor recommended     Latest

Info

You do not need all of these to get started. The absolute minimum is Python 3.10+ and the mcp package. But having the full toolchain will make your development experience dramatically better. I strongly recommend installing everything listed above.

Step 1: Python 3.10+

MCP's Python SDK requires Python 3.10 or later (for modern type hint syntax and match statements).

Check Your Current Version

Bash

python3 --version
# Should output: Python 3.10.x or higher

Install or Update Python

macOS (using Homebrew):

Bash

# Install Homebrew if you do not have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python@3.12

# Verify
python3 --version
# Python 3.12.x

Ubuntu/Debian:

Bash

sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev

# Verify
python3.12 --version

Windows:

powershell

# Download from python.org or use winget
winget install Python.Python.3.12

# IMPORTANT: Check "Add Python to PATH" during installation

# Verify (use python, not python3, on Windows)
python --version

Warning

On macOS, the system Python (/usr/bin/python3) is often outdated and managed by Apple. Always install a separate Python via Homebrew or pyenv. Never modify the system Python.

Verify pip

Bash

python3 -m pip --version
# pip 24.x from /path/to/python/site-packages (python 3.12)

Step 2: uv -- The Modern Python Package Manager

uv is a blazing-fast Python package manager written in Rust. It is 10-100x faster than pip and handles virtual environments automatically. The MCP ecosystem increasingly uses uv as the recommended package manager.

Concept Card

Install uv

Bash

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with Homebrew
brew install uv

# Or with pip
pip install uv

Verify uv

Bash

uv --version
# uv 0.5.x (or later)

# Test it by creating a quick project
mkdir mcp-test && cd mcp-test
uv init
uv add mcp

# This should complete in seconds, not minutes

Why uv Over pip?

Bash

# Speed comparison (typical install times):
# pip install mcp[cli]     ~45 seconds
# uv add mcp[cli]          ~3 seconds

# uv also handles:
# - Virtual environments (automatic)
# - Lock files (uv.lock)
# - Python version management (uv python install 3.12)
# - Running scripts (uv run)
# - Publishing packages

pip vs uv Install Speed

Before

pip install mcp[cli] -- 45 seconds, manual venv management, no lock file

After

uv add mcp[cli] -- 3 seconds, automatic venv, lock file, Python version management

Tip

If you are new to uv, think of it as "pip + venv + pyenv combined, but 50x faster." Once you try it, you will never go back to pip for project management. That said, pip works perfectly fine too -- use whatever you are comfortable with.

Step 3: Node.js 18+

Many MCP reference servers and tools are written in TypeScript and distributed via npm. You need Node.js to run them.

Check Your Current Version

Bash

node --version
# Should output: v18.x.x or higher (v20+ recommended)

npm --version
# Should output: 9.x.x or higher

Install Node.js

macOS (Homebrew):

Bash

brew install node@20

# Or use nvm for version management
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Ubuntu/Debian:

Bash

# Using NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Windows:

powershell

winget install OpenJS.NodeJS.LTS
# Or download from nodejs.org

Verify npx

npx is what you will use to run MCP reference servers without installing them globally:

Bash

npx --version
# 9.x.x or higher

# Quick test: run a simple package
npx cowsay "MCP is ready!"

Step 4: Install the MCP Python SDK and FastMCP

Now let us install the core MCP development packages.

Option A: Using uv (Recommended)

Bash

# Create your MCP development project
mkdir ~/mcp-dev && cd ~/mcp-dev

# Initialize a new Python project
uv init

# Add the MCP package with CLI extras
uv add "mcp[cli]"

# Verify the installation
uv run python -c "import mcp; print(f'MCP SDK version: {mcp.__version__}')"
# MCP SDK version: 1.x.x

# Verify FastMCP is available
uv run python -c "from mcp.server.fastmcp import FastMCP; print('FastMCP is ready!')"
# FastMCP is ready!

Option B: Using pip

Bash

# Create a virtual environment
python3 -m venv mcp-env
source mcp-env/bin/activate  # On Windows: mcp-envScriptsactivate

# Install MCP with CLI extras
pip install "mcp[cli]"

# Verify
python -c "from mcp.server.fastmcp import FastMCP; print('FastMCP is ready!')"

What Gets Installed

The mcp[cli] package includes:

mcp                 Core protocol implementation
  mcp.server        Server-side classes
  mcp.client        Client-side classes
  mcp.types         Protocol type definitions
  mcp.server.fastmcp  High-level FastMCP framework

CLI tools:
  mcp run           Run an MCP server
  mcp dev           Run server with Inspector attached
  mcp install       Install server in Claude Desktop

Dependencies:
  pydantic          Data validation and schemas
  httpx             Async HTTP client
  uvicorn           ASGI server (for HTTP transport)
  starlette         Web framework (for HTTP transport)
  anyio             Async runtime abstraction

Step 5: Create and Test Your First Server

Let us create a minimal server to verify everything works end to end.

Create the Server File

Bash

# Make sure you are in your project directory
cd ~/mcp-dev

Create a file called server.py:

Python

"""My first MCP server - a simple greeting service."""

from mcp.server.fastmcp import FastMCP

# Create the server instance
mcp = FastMCP("Hello MCP")


@mcp.tool()
def greet(name: str) -> str:
    """Greet someone by name.

    Args:
        name: The name of the person to greet
    """
    return f"Hello, {name}! Welcome to the world of MCP."


@mcp.tool()
def add(a: float, b: float) -> float:
    """Add two numbers together.

    Args:
        a: The first number
        b: The second number
    """
    return a + b


@mcp.resource("info://about")
def about() -> str:
    """Information about this MCP server."""
    return "This is a test MCP server for verifying your development environment."


@mcp.prompt()
def welcome_prompt(user_name: str) -> str:
    """Generate a welcome message for a new user.

    Args:
        user_name: The name of the user to welcome
    """
    return f"""You are a friendly AI assistant. Welcome {user_name} to the
MCP Mastery course. Be enthusiastic and encouraging. Explain that they have
successfully set up their development environment and are ready to start
building MCP servers."""


if __name__ == "__main__":
    mcp.run()

Run the Server

Bash

# Using uv
uv run mcp run server.py

# Or with pip (if you activated your venv)
mcp run server.py

# You should see output like:
# Starting MCP server "Hello MCP"...
# Server running on stdio transport

Warning

Do not let Setting Up Your MCP Development Environment become a hidden assumption. If teammates cannot see the rule, config, or verification path, Claude will behave inconsistently across sessions.

The server starts and waits for JSON-RPC messages on stdin. You will not see much output because it is waiting for a client to connect. Press Ctrl+C to stop it.

Step 6: The MCP Inspector

The Inspector is your most important development tool. It provides a web-based UI for interacting with MCP servers -- calling tools, browsing resources, and testing prompts without needing Claude Desktop.

Launch the Inspector

Bash

# Connect the Inspector to your server
npx @modelcontextprotocol/inspector uv run mcp run server.py

This opens a web browser at http://localhost:6274 (or a similar port) with the Inspector UI.

Using the Inspector

Once the Inspector opens, you will see three tabs: Tools, Resources, and Prompts.

Lists all tools your server exposes. Click on greet, enter a name, and click Call Tool to see the greeting response.

TOOLS TAB:
  Lists all tools your server exposes.
  For our test server, you will see:
    - greet (name: string)
    - add (a: number, b: number)

  Click on "greet", enter a name, and click "Call Tool"
  You should see: "Hello, [name]! Welcome to the world of MCP."

RESOURCES TAB:
  Lists all resources.
  You will see:
    - info://about

  Click on it to see the resource content.

PROMPTS TAB:
  Lists all prompt templates.
  You will see:
    - welcome_prompt (user_name: string)

  Enter a name and click "Get Prompt" to see the
  generated prompt template.

Inspector Pro Tips

Bash

# Run Inspector in development mode (auto-reloads on file changes)
npx @modelcontextprotocol/inspector uv run mcp dev server.py

# Connect to an already-running server on HTTP
npx @modelcontextprotocol/inspector --url http://localhost:8000/mcp

# Connect to an npm-based server
npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

Info

The Inspector communicates with your server using the exact same protocol that Claude Desktop uses. If your server works in the Inspector, it will work in Claude Desktop. This makes the Inspector the fastest way to iterate during development.

Step 7: Configure Claude Desktop

Now let us connect your test server to Claude Desktop so you can use it in real AI conversations.

Map Your Setting Up Your MCP Development Environment Layers

Open your global, project, and local Claude configuration files.
Write down which rule for this lesson belongs in each layer and why.
Start a fresh Claude Code session and confirm the effective behavior matches your intent.

Install Claude Desktop

Download Claude Desktop from claude.ai/download↗ if you have not already. Make sure you are on the latest version.

Edit the Configuration

The configuration file location depends on your OS:

Bash

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

# Windows
code %APPDATA%Claudeclaude_desktop_config.json

# Linux
code ~/.config/Claude/claude_desktop_config.json

Add your server to the configuration:

JSON

{
  "mcpServers": {
    "hello-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/Users/yourname/mcp-dev",
        "mcp", "run", "server.py"
      ]
    }
  }
}

If you used pip instead of uv:

JSON

{
  "mcpServers": {
    "hello-mcp": {
      "command": "/path/to/mcp-env/bin/python",
      "args": ["-m", "mcp", "run", "server.py"],
      "cwd": "/Users/yourname/mcp-dev"
    }
  }
}

Warning

After editing the configuration file, you must completely restart Claude Desktop (not just close the window -- quit the application and reopen it). On macOS, use Cmd+Q. On Windows, right-click the system tray icon and choose Quit.

Verify in Claude Desktop

After restarting, look for the MCP server indicator in Claude Desktop:

Open a new conversation
Look for the hammer icon (tools) near the message input
Click it to see available tools
You should see "greet" and "add" from your server

Try typing: "Can you greet Alice and then add 42 and 58?"

Claude should use your MCP tools to greet Alice and perform the addition.

Quick Check

What is the main benefit of using Setting Up Your MCP Development Environment well in Claude Code?

Step 8: Install Useful Reference Servers

While we are setting things up, let us add a few reference servers that you will use throughout this course:

JSON

{
  "mcpServers": {
    "hello-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/yourname/mcp-dev", "mcp", "run", "server.py"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

These give Claude the ability to:

filesystem: Read and search files in your projects directory
fetch: Retrieve and read web pages

Step 9: Verify Your Complete Setup

Run through this checklist to make sure everything is working:

MCP Development Workflow

Test your server in the Inspector first, then connect to Claude Desktop once it works

Don't

Skip the Inspector and go straight to Claude Desktop -- debugging is much harder without the Inspector UI

Bash

# 1. Python version
python3 --version
# Expected: Python 3.10+ (3.12 recommended)

# 2. uv installed
uv --version
# Expected: uv 0.4+

# 3. Node.js version
node --version
# Expected: v18+ (v20 recommended)

# 4. MCP SDK installed
uv run python -c "from mcp.server.fastmcp import FastMCP; print('OK')"
# Expected: OK

# 5. MCP CLI works
uv run mcp --help
# Expected: Usage information for the mcp command

# 6. Inspector launches (close with Ctrl+C after verifying)
npx @modelcontextprotocol/inspector uv run mcp run server.py
# Expected: Browser opens with Inspector UI

# 7. Claude Desktop shows your server
# Open Claude Desktop, check for tools icon
# Expected: greet and add tools visible

If all seven checks pass, your development environment is fully configured.

Project Structure for the Course

As we build through this course, I recommend organizing your files like this:

~/mcp-dev/
  pyproject.toml          # Project config (created by uv init)
  uv.lock                 # Lock file (created by uv)
  server.py               # Your test server (created above)

  servers/                # Individual server projects
    weather/
      server.py
    github_tools/
      server.py
    database/
      server.py

  examples/               # Code examples from lessons
    ch02/
    ch03/
    ch04/
    ch05/

Create this structure now:

Bash

cd ~/mcp-dev
mkdir -p servers/weather servers/github_tools servers/database
mkdir -p examples/ch02 examples/ch03 examples/ch04 examples/ch05

Troubleshooting Common Setup Issues

"command not found: uv"

Bash

# Add uv to your PATH
# For bash:
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh (macOS default):
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

"ModuleNotFoundError: No module named 'mcp'"

Bash

# Make sure you are using the right Python
which python3
# Should point to your installed Python, not system Python

# If using uv, always prefix with "uv run"
uv run python -c "import mcp"

# If using pip, make sure your venv is activated
source mcp-env/bin/activate
python -c "import mcp"

Claude Desktop Does Not Show Your Server

Bash

# 1. Check the config file is valid JSON
python3 -c "import json; json.load(open('path/to/claude_desktop_config.json'))"

# 2. Check the command path is absolute
# BAD:  "command": "python"
# GOOD: "command": "/usr/local/bin/python3"
# GOOD: "command": "uv"  (if uv is in PATH)

# 3. Check Claude Desktop logs
# macOS: ~/Library/Logs/Claude/
# Look for MCP-related errors

# 4. Test the command manually in terminal
uv run --directory /Users/yourname/mcp-dev mcp run server.py
# Should start without errors

Inspector Shows "Connection Failed"

Bash

# Make sure the server command works standalone first
uv run mcp run server.py
# Should start without errors (Ctrl+C to stop)

# Then try Inspector with the full command
npx @modelcontextprotocol/inspector uv run mcp run server.py

# If using a virtual environment, use the full path to python
npx @modelcontextprotocol/inspector /path/to/venv/bin/python -m mcp run server.py

Port Conflicts

Bash

# If Inspector says the port is in use
# Kill any existing Inspector processes
lsof -i :6274
# Then kill the PID shown

# Or specify a different port
npx @modelcontextprotocol/inspector --port 6275 uv run mcp run server.py

Try This Now

Complete the entire setup process from start to finish. Then create a custom MCP server with at least two tools that do something useful to you personally. Ideas: a tool that generates random passwords, a tool that converts between units, or a tool that looks up information in a local file. Test it in the Inspector and then connect it to Claude Desktop. When you can have a conversation with Claude that uses your custom tools, you know your environment is fully ready.

Key Takeaways

The MCP development stack requires Python 3.10+, Node.js 18+, the mcp Python package, and optionally the uv package manager
FastMCP is included in the mcp package and provides a decorator-based API for building servers quickly
The MCP Inspector is a web-based testing UI that is essential for development -- always test there before Claude Desktop
Claude Desktop configuration lives in a JSON file and requires a full application restart after changes
Use uv run mcp run server.py to start servers and npx @modelcontextprotocol/inspector to test them
Organize your course projects in a structured directory to keep examples manageable
When troubleshooting, always verify the server command works standalone before testing with Inspector or Claude Desktop