Build Your First MCP Server in 30 Minutes and Connect Claude Desktop

Build a working MCP server in 30 minutes. Step-by-step Python tutorial for beginners. Connect it to Claude Desktop and see it work. No MCP experience needed.

What you’ll build: A Python MCP server with one tool (read_note) that lets Claude Desktop read files from your computer. This is the same pattern used by every MCP server - from simple file readers to complex database connectors.

In this lesson, we finally move from ideas to something concrete.

You will build a simple MCP server that Claude Desktop can use to read notes from files on your computer. By the end, you will know exactly how to write a basic MCP server in Python, how to connect it to Claude Desktop, and how to see Claude use your custom tool in real conversations.

Everything runs on your laptop, and you’ll see it work inside Claude Desktop - a real AI application using your MCP server.

👋 Julley, I'm Dheeraj, an AI systems builder.

I build production-grade AI systems at work by day and ship my own products by night, 9 and counting, including SubflowAI and the Content OS Agents Toolkit. This newsletter is the bridge between those two worlds. Every system, every build, documented step by step.

Join 1,800+ builders getting the exact AI setups, prompts, and workflows that actually work in your business.

---

MCP Masterclass - Full Course

1. What Is MCP? Model Context Protocol Explained Simply

2. Why MCP Was Created: The AI Integration Problem It Solves

3. MCP Architecture Explained: Hosts, Clients, and Servers

4. MCP Tools, Resources, and Prompts: What Each One Does

5. Build Your First MCP Server in 30 Minutes ← You are here

6. Multi-Agent AI Collaboration Tutorial with MCP

7. How to Give Your AI Agents Persistent Memory with MCP

8. Build AI Agents That Learn and Improve From Experience

---

Building an MCP server isn’t about writing complex code. It’s about creating one simple tool that Claude Desktop can use to help you. Once you see it work, you’ll understand how to build anything.

Think about working alone on a project versus working with a skilled assistant.

Working Alone:

• You have to do every task yourself

• You can only access what’s in your head

• Every project starts from scratch

Working with an AI Assistant (Claude):

• You describe what you need

• The assistant helps you think and create

• But the assistant can only work with what you tell them directly

Working with Claude + MCP:

• Claude can now reach your files, tools, and data

• You describe what you need once

• Claude uses your custom tools to access exactly what’s needed

• Your assistant just became 10x more useful

That’s what we’re building today - the connection that turns Claude into a truly helpful AI assistant that can access your actual work.

Build an MCP Server and Connect Claude Desktop

---

Before You Start: What You Need

This tutorial uses Python. You don’t need to be an expert - if you can copy and paste code and run commands in a terminal, you can build this MCP server.

You’ll need:

• Python 3.8 or newer installed on your computer

• A code editor (VS Code, Cursor, or PyCharm all work)

• Claude Desktop (free or paid account)

• About 30 minutes

If you’re not sure whether Python is installed, open a terminal and run python3 --version. If you see a version number, you’re good to go.

---

Step 1: Set Up Your Project in 5 Minutes

Before we write any code, let’s prepare a clean workspace.

1. Create a new folder on your computer

2. Name it: mcp_lesson_5

3. Open this folder in your code editor (VS Code, Cursor, or PyCharm)

We use a virtual environment so this project doesn’t interfere with anything else on your machine.

If you use macOS or Linux, run these commands in a terminal inside the folder:

python3 -m venv .venv
source .venv/bin/activate

If you use Windows, run:

py -m venv .venv
.venv\Scripts\activate

After this, you should see something like:

(.venv) yourname@mcp_lesson_5 %

That means the virtual environment is active. If you want to leave it later, type deactivate.

Install the MCP Python SDK

Run this inside the same terminal while the environment is active:

pip install mcp

This installs the official Python SDK for MCP which has everything you need to build an MCP server.

If pip is not found, reinstall Python from the official site and make sure to check “Add Python to PATH” during installation.

Install Claude Desktop

Claude Desktop will act as your MCP Host - the application that connects to your server and lets the AI model use your tools.

1. Go to claude.ai/download

2. Download Claude Desktop for your operating system (macOS or Windows)

3. Install it and sign in with your Claude account

Note: You need a Claude account (free or paid) to use Claude Desktop.

Verify Your Setup

Create a new file in the project folder called check_setup.py. Paste this code:

# This script verifies that the MCP SDK is installed correctly

try:
    from mcp.server import Server
    from mcp.server.stdio import stdio_server
    from mcp.types import Tool, TextContent

    print("✓ MCP SDK is installed correctly!")
    print("✓ All required components are available")
    print("\nYou're ready to build your first MCP server!")

except ImportError as e:
    print("✗ MCP SDK installation issue detected:")
    print(f"  Error: {e}")
    print("\nPlease run: pip install mcp")

Run it with python check_setup.py. If you see two lines printed with no errors, you’re ready to build.

---

Commercial break: Claude Code Builder cohort

The founding batch of my Claude Code cohort starts in July on Maven. Four weeks, six sessions. Learn to build the AI system with me.

Only 12 Seats. When they’re gone, the founding price ($797) closes and Cohort 2 opens at $1,597.

Use code GENAI20 for 20% off. Expires July 9. Check the Syllabus →

---

Step 2: What You’re Going to Build

We will build the simplest possible useful MCP project:

The Idea:

1. A text file on your computer holds some notes

2. An MCP server exposes a tool that can read that file

3. You configure Claude Desktop to connect to your server

4. Inside Claude Desktop, you ask Claude to read your note

5. Claude uses your MCP tool to get the file content

6. Claude shows you the content or summarizes it

The Flow:

You ask Claude a question → Claude Desktop (the Host) → Your MCP Server → File on disk → Back to Claude Desktop → Claude reads it and responds → You see the answer

Once you understand this pattern, you can replace the file with anything:

• A database

• A Notion page

• A Google Sheet

• An API endpoint

The structure stays the same. This is the pattern used by every MCP server out there - from simple file readers to complex database connectors.

Create the Sample File

Before we write the server, let’s create the file it will read.

In your project folder, create a file called sample_note.txt. Add some text inside, for example:

This is my first MCP server.
MCP lets Claude Desktop connect to tools I create.
Those tools can read data, write data, or trigger actions.
Now Claude can use my custom tools to help me get work done.

Save the file.

---

Step 3: Write Your MCP Server (Hello World Pattern)

Now let’s create the server that exposes the read_note tool.

Create a file called server.py. Paste this code:

import asyncio
from pathlib import Path
from mcp.server.models import InitializationOptions
from mcp.server import NotificationOptions, Server
from mcp.server.stdio import stdio_server
from mcp.types import TextContent, Tool

# Create the server instance
server = Server("note-reader")

# Define what tools this server offers
@server.list_tools()
async def handle_list_tools() -> list[Tool]:
    """List available tools"""
    return [
        Tool(
            name="read_note",
            description="Read a text file from the local filesystem",
            inputSchema={
                "type": "object",
                "properties": {
                    "filename": {
                        "type": "string",
                        "description": "Name of the file to read (e.g., 'sample_note.txt')"
                    }
                },
                "required": ["filename"]
            }
        )
    ]

# Handle tool calls
@server.call_tool()
async def handle_call_tool(name: str, arguments: dict) -> list[TextContent]:
    """Execute a tool"""
    if name != "read_note":
        raise ValueError(f"Unknown tool: {name}")

    filename = arguments.get("filename")
    if not filename:
        raise ValueError("Missing required argument: filename")

    # Get the file path
    file_path = Path(__file__).parent / filename

    # Check if file exists
    if not file_path.exists():
        return [TextContent(
            type="text",
            text=f"Error: File '{filename}' not found in the server directory."
        )]

    # Read and return the file content
    try:
        content = file_path.read_text(encoding="utf-8")
        return [TextContent(
            type="text",
            text=content
        )]
    except Exception as e:
        return [TextContent(
            type="text",
            text=f"Error reading file: {str(e)}"
        )]

async def main():
    """Main entry point for the server"""
    async with stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="note-reader",
                server_version="1.0.0",
                capabilities=server.get_capabilities(
                    notification_options=NotificationOptions(),
                    experimental_capabilities={},
                )
            )
        )

if __name__ == "__main__":
    asyncio.run(main())

Here’s what each part does:

• Server(”note-reader”) creates an MCP server with a name

• @server.list_tools() tells Claude Desktop what tools are available

• @server.call_tool() handles when Claude asks to use a tool

• read_note tool takes a filename, reads it, and returns the content

• stdio_server() sets up communication through standard input/output (how Claude Desktop will talk to your server)

• server.run() starts the server and waits for requests

This is the MCP server Python template that scales to any use case. The tool definitions and handlers are what change - the server structure stays exactly the same.

---

Step 4: Connect Your Server to Claude Desktop

Now we need to tell Claude Desktop about your server. This is the “how to connect MCP server to Claude Desktop” step that many tutorials gloss over - let’s do it right.

Find Your Python Path

We need the full path to your Python executable inside the virtual environment.

On macOS/Linux, run: which python

On Windows, run: where python

Copy the full path. It will look something like:

• macOS/Linux: /Users/yourname/mcp_lesson_5/.venv/bin/python

• Windows: C:\Users\yourname\mcp_lesson_5\.venv\Scripts\python.exe

Find Your server.py Path

Get the full path to your server.py file.

Easy way:

• In VS Code/Cursor: Right-click server.py → Copy Path

• Or manually combine your project folder path + /server.py

Example:

• macOS/Linux: /Users/yourname/mcp_lesson_5/server.py

• Windows: C:\Users\yourname\mcp_lesson_5\server.py

Edit the Claude Desktop Config

1. Open Claude Desktop

2. Click on your profile icon (bottom-left) → Settings

3. Go to the Developer tab

4. Click Edit Config

This opens the claude_desktop_config.json file. Add this configuration (replace the paths with YOUR paths from the steps above):

Example for macOS:

{
  "mcpServers": {
    "note-reader": {
      "command": "/Users/john/mcp_lesson_5/.venv/bin/python",
      "args": [
        "/Users/john/mcp_lesson_5/server.py"
      ]
    }
  }
}

Example for Windows:

{
  "mcpServers": {
    "note-reader": {
      "command": "C:\\Users\\john\\mcp_lesson_5\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\john\\mcp_lesson_5\\server.py"
      ]
    }
  }
}

Important: Use double backslashes (\\) in Windows paths in JSON files.

Save the file and completely quit and restart Claude Desktop.

• Your system may prompt you to allow access to a volume or file location for Claude.

• Click allow to provide access to disk volumes and the file system.

---

This tutorial promises 30 minutes to a working MCP server. But the code spans 4 separate files. Without the source ready to copy, hunting GitHub for the right version or typing it out by hand adds 45-60 minutes before you debug a single thing.

PluggedIn members get the complete source code, the MCP quick reference card, and the full 8-lesson ebook in one place - so that 30-minute promise actually holds.

---

Step 5: Test Your Server With MCP Inspector

After restarting Claude Desktop, let’s verify your server is connected:

1. Open Claude Desktop

2. Start a new conversation

3. Look at the bottom-right corner of the message input box

4. You should see a Search and tools icon

5. Click on it. You should see “note-reader” as a tool under it:

What This Means:

• note-reader = Your server is connected and running

• read_note = Your tool is available for Claude to use

If you don’t see the tools icon or your server, jump to the Troubleshooting section below.

Pro tip: The MCP Inspector is an official debugging tool from the MCP team that lets you test your server’s tools and resources without Claude Desktop. It’s worth bookmarking for when you build more complex servers.

Run Your First Test

In Claude Desktop, type:

“Can you use the read_note tool to read sample_note.txt?”

What will happen:

1. Claude recognizes it needs to use your read_note tool

2. A popup appears asking: “Claude wants to use the read_note tool. Allow?”

3. Click “Allow once” 4. Your MCP server runs in the background 5. The file content appears in Claude’s response

You’ll see something like:

Try these follow-ups:

• “Summarize that note in one sentence”

• “What does the note say about tools?”

• “Turn the note into a haiku”

Claude now has access to your local files through your MCP server.

---

Understanding What Just Happened

Let’s understand the complete flow:

1. You asked Claude a question in Claude Desktop

2. Claude Desktop (the Host) received your message

3. The AI model decided it needed the read_note tool

4. Claude Desktop’s Client translated that into MCP language

5. Your MCP Server received the request, read the file, and sent back the content

6. The AI model received the file content and used it to answer you

7. Claude Desktop showed you the response

This is the core MCP pattern: User Request -> Host -> Client -> Server -> Tool -> Back to AI model -> Response

You can read more about this architecture in the MCP Architecture guide from earlier in this course. The official Model Context Protocol documentation at modelcontextprotocol.io also covers this flow in detail.

---

Troubleshooting: When Things Go Wrong

Check 1: Did you restart Claude Desktop completely? (Quit the app entirely - don’t just close the window)

Check 2: Are your paths correct in the config file?

• Run your Python path in terminal to verify it works

• Check that server.py exists at the path you specified

Check 3: Check Claude Desktop logs:

• macOS: ~/Library/Logs/Claude/mcp*.log

• Windows: %APPDATA%\Claude\logs\mcp*.log

Look for error messages about your server.

If Claude can’t read files:

• The file sample_note.txt must be in the same folder as server.py

• The file must have read permissions

If the tool appears but crashes when used:

• Run python server.py manually in your terminal

• It should start without errors and wait (it won’t print anything)

• Press Ctrl+C to stop it

• If you see Python errors, fix them in your server.py code

---

What You Actually Built

You just did something powerful: you gave Claude Desktop access to your local files through a tool you control.

This is different from:

• Uploading files to a chat (limited, manual, one-time)

• Copy-pasting content (tedious, error-prone)

• Using built-in features (restricted to what the app allows)

What you built:

• A tool that works with any text file

• Complete control over what Claude can access

• Permission-based (you approve every use)

• A pattern you can use for databases, APIs, anything

Real-world applications:

• Read project documentation and answer questions about it

• Summarize meeting notes from multiple files

• Search through your research papers

• Extract data from reports

• Process customer support tickets from files

The same structure you built today scales to:

• Connecting to databases

• Calling external APIs

• Triggering automation workflows

• Reading from Notion, Google Drive, or Slack

That’s the power of MCP: One simple pattern, infinite possibilities.

---

Practice Exercises

Before moving to the next lesson, try this:

1. Create a second text file called project_notes.txt with some random project notes

2. Ask Claude: “Can you read project_notes.txt and tell me what it says?”

3. Watch it work - Claude uses your tool to read the new file

Then try asking Claude:

Read both sample_note.txt and project_notes.txt and compare them

You’ll see Claude use your tool multiple times in one conversation. That’s the beginning of real automation.

Want to experiment more? Try these:

1. Modify the tool to list all .txt files in the folder

2. Add error handling for when files don’t exist (already done, but experiment with improving the messages)

3. Create a new tool that counts words in a file

---

Key Takeaways

In this lesson, you learned:

• How to set up a clean Python environment for MCP development

• How to write a simple MCP server with one tool

• How to configure Claude Desktop to connect to your server

• How to see a real AI application use your custom tool

• The complete flow: User -> Claude -> MCP Server -> Tool -> Response

• The core pattern that all MCP systems use

• How to give AI models access to your local data safely

This is the foundation. Everything that follows - multiple agents, memory systems, autonomous workflows - builds on this same pattern.

---

GitHub Repository

You’ve just built your first working MCP server, and that’s a real achievement. As we move into the advanced lessons, you’ll build increasingly complex systems with multiple tools, shared memory, and autonomous workflows. Managing all that code across lessons can get messy fast.

That’s why I’ve created a companion GitHub repository for this entire course:

MCP Masterclass GitHub Repository

Clone it to your computer now, even before you start the next lesson. The working code for this lesson is in the lesson-05 folder.

---

Frequently Asked Questions

Can I build an MCP server without coding?

Not yet. Building a custom MCP server requires Python or TypeScript. However, you can use hundreds of pre-built MCP servers from the community without writing code - just configure them in Claude Desktop.

What language do I need for an MCP server?

The official MCP SDKs support Python and TypeScript/JavaScript. This tutorial uses Python. Both languages work equally well - choose whichever you’re more comfortable with. Java, Kotlin, and C# SDKs also exist.

How do I test my MCP server?

You can test directly through Claude Desktop (as shown in this tutorial) or use MCP Inspector, an official debugging tool that lets you test tools and resources without an AI model. MCP Inspector is available from the official MCP documentation.

How long does building an MCP server take?

About 30 minutes for your first basic server using this tutorial. Once you understand the pattern, adding new tools to an existing server takes 10-15 minutes.

Can my MCP server connect to APIs and databases?

Yes. The file-reading server in this tutorial is just the starting point. The same pattern works for any data source: databases, REST APIs, Google Sheets, Notion, Slack, and more. Replace the file-reading logic with your API calls.

What’s next after your first server?

The natural next steps are: adding more tools to the same server, connecting to external APIs, and then building multi-agent systems where multiple servers collaborate. Later lessons in this course cover all of these.

---

Get PluggedIn

Stop reading about MCP servers and run one - with Claude Desktop calling your tool in a real conversation, not just in theory.

See what’s included →

Without the source files in hand, that 30-minute build costs you 45-60 minutes before you write a single line.

Get PluggedIn to go from following a tutorial with missing code blocks to running a live MCP server Claude Desktop actually calls in under 30 minutes

What’s inside the MCP Mastery Bundle:

• Complete 8-lesson ebook (PDF)

• MCP quick reference card (PDF)

• All source code on GitHub

---

What’s Next

In the multi-agent collaboration tutorial, we’re going to explore something exciting: how multiple AI agents can collaborate through MCP to accomplish tasks that would be difficult for a single agent working alone.

You’ll see the patterns from this lesson extended into a real multi-agent workflow.

PS: Every time Claude reads a file using your tool, remember: You built that connection. That’s your MCP server at work, safely giving Claude access to your local data with your permission.