MCP Learning Project 2025 🚀
A hands-on project to demonstrate building and deploying Model Context Protocol (MCP) servers. Learn how to create custom MCP tools, configure them for AI assistants, and integrate them with Claude Desktop, Continue, and other MCP-compatible applications.
🎯 What You'll Learn
🛠️ Build custom MCP servers from scratch
🔌 Integrate MCP tools with AI assistants
🧪 Test and debug using MCP Inspector and MCP Studio
📦 Manage dependencies with UV or pip
🚀 Deploy production-ready MCP servers
🎨 Create type-safe tools with Pydantic
🌐 Use streamable HTTP transport for advanced scenarios
🏗️ Tech Stack
Category | Technology | Purpose |
Language | Python 3.13+ | Core programming language |
Protocol | MCP (Model Context Protocol) | Standardized AI-tool communication |
Framework | FastMCP | Rapid MCP server development |
Package Manager | UV or pip + venv | Dependency management |
Validation | Pydantic | Data validation and type safety |
Server | Uvicorn | ASGI server for MCP |
Testing | MCP Inspector & MCP Studio | Interactive testing and debugging |
📋 Prerequisites
Before diving in, make sure you have:
✅ Python 3.13+ installed on your system
✅ UV (recommended) or pip + venv for package management
✅ VS Code (optional but recommended for MCP configuration)
✅ Git for version control
✅ Terminal access (PowerShell, CMD, or Bash)
🚀 Installation
1. Install UV:
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
2. Initialize project:
# Create new project
uv init learn-mcp-2025
cd learn-mcp-2025
# Or in existing directory
uv init
3. Add MCP dependencies:
# Add MCP with CLI tools
uv add "mcp[cli]"
# This creates/updates:
# - pyproject.toml
# - uv.lock
4. Install all dependencies:
1. Navigate to project:
2. Create virtual environment:
3. Activate virtual environment:
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# Windows (CMD)
.venv\Scripts\activate.bat
4. Install dependencies:
# From requirements.txt
pip install -r requirements.txt
# Or install package in editable mode
pip install -e .
Generated Files
UV | pip + venv |
pyproject.toml - Project metadata and dependencies
| requirements.txt - Pinned dependencies
|
uv.lock - Locked dependency versions
| .venv/ - Virtual environment directory
|
⚙️ MCP Server Configuration
To integrate your MCP server with AI clients (like Claude Desktop), create a configuration file:
Create .vscode/mcp.json
{
"servers": {
"weather-service": {
"command": "python",
"args": ["weather.py"],
"env": {}
}
}
}
Multi-Server Configuration
{
"servers": {
"weather-service": {
"command": "python",
"args": ["weather.py"],
"env": {}
},
"winget-mcp": {
"type": "stdio",
"command": "C:\\Users\\YourUser\\AppData\\Local\\Microsoft\\WindowsApps\\...\\WindowsPackageManagerMCPServer.exe"
}
}
}
Configuration Options
Field | Description | Example |
command
| Executable to run | python, node, uv
|
args
| Arguments passed to command | ["weather.py"], ["run", "server.py"]
|
env
| Environment variables | {"API_KEY": "value"}
|
type
| Communication type | stdio (default)
|
🎮 Running the MCP Server
Method 1: Quick Testing ⚡ (Direct Function Call)
Test individual functions without starting the full MCP server:
uv run python -c "from weather import get_weather; print(get_weather('London'))"
Output:
The current weather in London is sunny with a temperature of 25°C.
# Activate venv first
.venv\Scripts\Activate.ps1
# Then run
python -c "from weather import get_weather; print(get_weather('London'))"
Output:
The current weather in London is sunny with a temperature of 25°C.
When to use:
✅ Fast iteration during development
✅ Unit testing individual tools
✅ Debugging function logic
❌ Won't work with MCP clients
Method 2: Production Mode 🚀 (Full MCP Server)
Run as a complete MCP server for AI assistant integration:
# Start MCP server
uv run python weather.py
# The server will start and listen for MCP requests
# Activate venv first
.venv\Scripts\Activate.ps1
# Start MCP server
python weather.py
When to use:
✅ Integration with AI assistants (Claude, Continue, etc.)
✅ Production deployments
✅ Multi-tool servers
✅ Standardized MCP protocol communication
Method 3: MCP Inspector 🔍 (Development & Debugging)
Use the MCP Inspector to interactively test your server with a web UI:
With UV:
# Start MCP dev mode
uv run mcp dev <your-server.py>
With pip + venv:
# Activate venv first
.venv\Scripts\Activate.ps1
# Start MCP dev mode
mcp dev <your-server.py>
Features:
Terminal-based debugging
Log output in console
Quick server validation
❌ No web UI
With UV:
# No installation needed - npx downloads temporarily
npx @modelcontextprotocol/inspector uv run <your-server.py>
With pip + venv:
# Activate venv first
.venv\Scripts\Activate.ps1
# Run inspector with Python
npx @modelcontextprotocol/inspector python <your-server.py>
Features:
MCP Inspector Features:
🔍 Interactive tool testing in browser
📊 Request/response inspection
🐛 Real-time debugging
📝 Schema validation
🎨 Visual interface for all MCP tools
Access Inspector:
Open browser: http://localhost:5173
Example with weather.py:
$ npx @modelcontextprotocol/inspector uv run weather.py
MCP Inspector running at http://localhost:5173
Server: Weather Service
Tools available: get_weather
Method 4: Python Client 🐍 (Programmatic Access)
Use Python code to connect to MCP servers programmatically:
Example 1: Connect to Weather Service (Python Server)
# Run the weather client
python client.py
Example 2: Connect to Airbnb Service (Node.js Server)
# Run the Airbnb client (connects to Node.js server via npx)
python client_airbnb.py
Client Features:
📡 Programmatic MCP server connections
🔄 Async/await communication patterns
🌐 Cross-language support (Python ↔ Node.js)
🛠️ Direct tool invocation from code
📋 Dynamic tool discovery with list_tools()
When to use:
✅ Building MCP-powered applications
✅ Automating tool calls in scripts
✅ Testing server integrations
✅ Creating custom MCP workflows
✅ Connecting to third-party MCP servers
Method 5: MCP Studio 🛠️ (Advanced Testing & Streamable Transport)
MCP Studio provides advanced debugging capabilities, especially for streamable HTTP transports and complex server integrations.
Setup MCP Studio
1. Install MCP Studio:
npm install -g @modelcontextprotocol/studio
2. Configure Remote Server in
{
"servers": {
"remote-example": {
"command": "npx",
"args": ["mcp-remote", "http://127.0.0.1:8000"]
}
}
}
3. Run Streamable Server:
# Start the streamable server on HTTP transport
uv run python sample_mcp_streamable_server.py
# Server runs on http://127.0.0.1:8000 (or configured port)
4. Connect with MCP Studio:
# Launch MCP Studio and connect to remote server
mcp-studio --remote http://127.0.0.1:8000
MCP Studio Benefits:
Visual Debugging: Interactive UI for tool calls and responses
Streamable Transport Support: Handles HTTP/SSE connections for streamable servers
Real-time Monitoring: Live logs and error tracking
Multi-Server Testing: Test multiple servers simultaneously
Integration Testing: Simulate AI assistant interactions
When to use MCP Studio:
✅ Testing streamable HTTP servers
✅ Complex multi-tool integrations
✅ Production-like testing scenarios
✅ Debugging connection issues
📁 Project Structure
learn-mcp-2025/
├── .github/
│ ├── copilot-instructions.md # AI agent development guidelines
│ └── prompts/ # Reusable prompt templates
├── .vscode/
│ └── mcp.json # MCP server configuration for VS Code/AI assistants
├── .venv/ # Virtual environment (pip only)
│
├── MCP Servers (Tools for AI Assistants)
├── weather__mcp_server.py # 🔧 Weather service tools
├── crypto_mcp_server.py # 🔧 Cryptocurrency price tools
├── local_notes_mcp_server.py # 🔧 Local notes management (add/get)
├── screenshot_tool.py # 🔧 Screenshot capture tool
├── pydantic_schema_person_server.py # 🔧 Person data schema & processing
├── resources_mcp_server.py # 🔧 Resource management (coffee inventory)
├── websearch_mcp_server.py # 🔧 Web search functionality
├── sample_mcp_streamable_server.py # 🔧 Streamable HTTP transport example
│
├── MCP Clients (Test & Integration)
├── weather_mcp_client.py # 🔌 Client for weather server
├── airbnb_mcp_client.py # 🔌 Client for Airbnb server (Node.js)
├── resources_mcp_client.py # 🔌 Client for resources server
│
├── Configuration & Dependencies
├── pyproject.toml # Project metadata & dependencies (UV)
├── requirements.txt # Pinned dependencies (pip)
├── uv.lock # Locked dependency versions (UV)
├── .python-version # Python version specification
├── .gitignore # Git ignore rules
├── notes.txt # Data file for local_notes_mcp_server
├── log.txt # Log file for person data
└── README.md # This file
Key Files Explained
File | Type | Purpose |
weather__mcp_server.py
| MCP Server | Weather service with mock weather data tools |
crypto_mcp_server.py
| MCP Server | Cryptocurrency price lookup tools |
local_notes_mcp_server.py
| MCP Server | File-based notes management (add/get) |
screenshot_tool.py
| MCP Server | Screenshot capture using Pillow |
pydantic_schema_person_server.py
| MCP Server | Person data schema & processing with validation |
resources_mcp_server.py
| MCP Server | Resource management (coffee inventory example) |
websearch_mcp_server.py
| MCP Server | Web search functionality |
sample_mcp_streamable_server.py
| MCP Server | Streamable HTTP transport example |
weather_mcp_client.py
| MCP Client | Python client connecting to weather server |
airbnb_mcp_client.py
| MCP Client | Python client connecting to Node.js Airbnb server |
resources_mcp_client.py
| MCP Client | Python client for resources server |
pyproject.toml
| Config | Modern Python project configuration (PEP 621) |
requirements.txt
| Config | Traditional pip dependency list (auto-generated) |
uv.lock
| Config | UV's deterministic dependency lock file |
.vscode/mcp.json
| Config | MCP server registry for VS Code/Claude Desktop |
📚 Quick Command Reference
UV Commands 🔮
Command | Description |
uv init
| Initialize new Python project |
uv add <package>
| Add dependency to project |
uv remove <package>
| Remove dependency |
uv sync
| Install/sync all dependencies |
uv run <command>
| Run command in project environment |
uv pip list
| List installed packages |
uv pip show <package>
| Show package details |
uv lock
| Update lock file |
uv python install <ver>
| Install Python version |
uv python list
| List available Python versions |
pip + venv Commands 🐍
Command | Description |
python -m venv .venv
| Create virtual environment |
.venv\Scripts\Activate.ps1
| Activate venv (PowerShell) |
.venv\Scripts\activate.bat
| Activate venv (CMD) |
pip install -r requirements.txt
| Install dependencies |
pip install -e .
| Install package in editable mode |
pip install <package>
| Install single package |
pip uninstall <package>
| Remove package |
pip list
| List installed packages |
pip show <package>
| Show package details |
pip freeze > requirements.txt
| Export dependencies |
deactivate
| Deactivate virtual environment |
MCP Commands 🔧
Command | Description |
mcp dev <file>
| Start MCP Inspector for development |
mcp --version
| Check MCP CLI version |
python <file>.py
| Start MCP server in production |
npx @modelcontextprotocol/inspector uv run <file>
| Interactive MCP testing |
mcp-studio --remote <url>
| Advanced MCP Studio testing |
💡 Development Examples
Example 1: Adding a New Weather Tool 🌤️
Edit weather.py:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Weather Service")
@mcp.tool()
def get_weather(location: str) -> str:
"""Get current weather for a location."""
return f"The current weather in {location} is sunny with a temperature of 25°C."
@mcp.tool()
def get_forecast(location: str, days: int = 7) -> str:
"""Get weather forecast for the next N days."""
return f"Forecast for {location} for the next {days} days: Mostly sunny"
@mcp.tool()
def get_temperature(location: str, unit: str = "celsius") -> str:
"""Get current temperature in specified unit."""
temp = 25 if unit == "celsius" else 77
return f"Temperature in {location}: {temp}°{unit[0].upper()}"
if __name__ == "__main__":
mcp.run()
Example 2: Testing New Tools ✅
# Test with UV
uv run python -c "from weather import get_forecast; print(get_forecast('Paris', 5))"
# Test with pip/venv
python -c "from weather import get_forecast; print(get_forecast('Paris', 5))"
Example 3: Adding Type Safety 🔒
from typing import Literal
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Weather Service")
@mcp.tool()
def get_temperature(
location: str,
unit: Literal["celsius", "fahrenheit"] = "celsius"
) -> str:
"""Get temperature with validated unit parameter."""
temp = 25 if unit == "celsius" else 77
return f"Temperature in {location}: {temp}°{unit[0].upper()}"
Example 4: Building a Python MCP Client 🔌
# client.py
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio
server_params = StdioServerParameters(
command="uv",
args=["run", "weather.py"]
)
async def main():
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# Call a tool
result = await session.call_tool(
"get_weather",
arguments={"location": "Tokyo"}
)
print(result)
# List all available tools
tools = await session.list_tools()
print(f"Available tools: {tools}")
if __name__ == "__main__":
asyncio.run(main())
Example 5: Cross-Language MCP Integration 🌐
Connect Python client to Node.js MCP server:
# client_airbnb.py
server_params = StdioServerParameters(
command="npx",
args=["-y", "@openbnb/mcp-server-airbnb"]
)
async def main():
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# Discover tools from Node.js server
tools = await session.list_tools()
print(f"Airbnb MCP Tools: {tools}")
Example 6: Streamable HTTP Transport 🌐
For advanced scenarios requiring HTTP-based communication:
# sample_mcp_streamable_server.py
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Streamable MCP Server")
@mcp.tool()
def greet(name: str) -> str:
"""Greets the user with their name."""
return f"Hello, {name}! Hope you're having a great day! 😊"
if __name__ == "__main__":
# Use streamable HTTP transport for advanced scenarios
mcp.run(transport="streamable-http")
Testing Streamable Servers:
# Start server
uv run python sample_mcp_streamable_server.py
# Test with MCP Studio (in another terminal)
mcp-studio --remote http://127.0.0.1:8000
Example 7: Debugging & Verification 🐛
# List all tools in your server
uv run python -c "from weather import mcp; print(mcp.list_tools())"
# Check Python version
uv run python --version
# Verify MCP package
uv pip show mcp
# Test imports
uv run python -c "from weather import mcp; print('MCP initialized successfully')"
# Run client tests
python client.py
python client_airbnb.py
🤝 Contributing
This is a learning project! Feel free to:
🐛 Report bugs or issues
💡 Suggest new MCP tools
📝 Improve documentation
🔀 Submit pull requests
📄 License
This project is for learning purposes.
Built with ❤️ for learning MCP
⭐ Star this repo if you found it helpful!
🐙 GitHub • 📚 MCP Docs • 🔧 FastMCP
