Building Your First Model Context Protocol (MCP) Server with Python

1. Introduction

In a previous post, we explored the concepts behind the Model Context Protocol (MCP) – a way for AI assistants to securely interact with your local environment and external tools. MCP bridges the gap between isolated AI models and the rich context of your development workflow.

But how do you actually create one of these servers to extend an AI’s capabilities? This post provides a hands-on tutorial for building a simple, functional MCP server from scratch using Python.

Our goal is to create a server that exposes a single, straightforward tool: get_cwd. When called by an MCP client (like an integrated AI assistant), this tool will simply return the current working directory where the server script is running. This example, while basic, covers the fundamental communication patterns and structure of an MCP server.

2. Prerequisites

Before we start, make sure you have the following:

• Python 3.x: Ensure Python 3 is installed on your system. You can check with python --version or python3 --version.
• Basic Python & Command Line Knowledge: Familiarity with Python syntax, standard libraries, and navigating directories in your terminal.
• Code Editor: Any text editor will work, but VS Code, PyCharm, etc., are recommended.
• MCP Client: An AI assistant or development tool capable of discovering and interacting with MCP servers (like the environment you might be using right now!). This is needed for configuration and testing.

3. Understanding MCP Communication (Python Context)

At its core, MCP communication relies on exchanging structured JSON messages over standard input (stdin) and standard output (stdout).

1. Client -> Server: The MCP client (your AI tool) sends a JSON request object to the server’s stdin.
2. Server -> Client: The MCP server processes the request and sends a JSON response object (or an error object) back to the client via its stdout.

While official SDKs exist for languages like Node.js (@modelcontextprotocol/sdk) that abstract some of this, we’ll implement the protocol directly in Python for this tutorial. This gives us a clearer understanding of the underlying mechanism and requires only Python’s built-in libraries (json, sys, os).

4. Project Setup

Let’s set up our project directory and environment.

1. Create Project Directory:

   1 2	mkdir python_cwd_server cd python_cwd_server

2. Set up Virtual Environment: Using a virtual environment is crucial to manage dependencies.

   1	python3 -m venv .venv

   Activate it:

   • Linux/macOS: source .venv/bin/activate
   • Windows (Command Prompt): .\.venv\Scripts\activate.bat
   • Windows (PowerShell): .\.venv\Scripts\Activate.ps1 Your terminal prompt should now indicate you’re inside the .venv environment.

3. Create Server Script:

   1	touch main.py

   (On Windows, you might use type nul > main.py or create it via your editor).

5. Implementing the Server Logic (main.py)

Open main.py in your editor. We’ll build the core server logic step-by-step.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import sys
import json
import os
import logging

# Basic logging setup (optional but helpful for debugging)
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

def send_response(response_dict):
    """Sends a JSON response object to stdout."""
    response_json = json.dumps(response_dict)
    logging.info(f"Sending response: {response_json}")
    print(response_json, flush=True) # flush=True is important!

def send_error(request_id, code, message):
    """Sends a JSON-RPC error response."""
    error_response = {
        "jsonrpc": "2.0",
        "id": request_id,
        "error": {
            "code": code,
            "message": message
        }
    }
    send_response(error_response)

# MCP Error Codes (subset)
ERROR_METHOD_NOT_FOUND = -32601
ERROR_INVALID_PARAMS = -32602
ERROR_INTERNAL = -32603

def handle_list_tools(request_id):
    """Handles the ListTools request."""
    tools = [
        {
            "name": "get_cwd",
            "description": "Gets the server's current working directory.",
            # No parameters needed for this tool
            "inputSchema": { "type": "object", "properties": {} }
        }
    ]
    response = {
        "jsonrpc": "2.0",
        "id": request_id,
        "result": {
            "tools": tools
        }
    }
    send_response(response)

def handle_call_tool(request_id, params):
    """Handles the CallTool request."""
    tool_name = params.get("name")

    if tool_name == "get_cwd":
        try:
            cwd = os.getcwd()
            response = {
                "jsonrpc": "2.0",
                "id": request_id,
                "result": {
                    # Content should be an array of ContentPart objects
                    "content": [
                        {
                            "type": "text",
                            "text": f"Current Working Directory: {cwd}"
                        }
                    ]
                }
            }
            send_response(response)
        except Exception as e:
            logging.error(f"Error getting CWD: {e}")
            send_error(request_id, ERROR_INTERNAL, f"Failed to get current directory: {e}")
    else:
        # Tool not found
        send_error(request_id, ERROR_METHOD_NOT_FOUND, f"Tool '{tool_name}' not found.")

def main():
    """Main request handling loop."""
    logging.info("Python MCP Server started. Waiting for requests on stdin...")
    for line in sys.stdin:
        logging.info(f"Received line: {line.strip()}")
        try:
            request = json.loads(line)
            request_id = request.get("id")
            method = request.get("method")
            params = request.get("params", {})

            if not all([request.get("jsonrpc") == "2.0", method, request_id is not None]):
                 # Send a general error if basic JSON-RPC structure is wrong
                 # Note: A robust server might handle batch requests etc.
                 if request_id is not None:
                     send_error(request_id, -32600, "Invalid Request structure")
                 else:
                     # Cannot reply if ID is missing
                     logging.error("Received invalid request with no ID.")
                 continue # Skip processing this line

            if method == "ListTools":
                handle_list_tools(request_id)
            elif method == "CallTool":
                handle_call_tool(request_id, params)
            else:
                # Method not supported by this simple server
                send_error(request_id, ERROR_METHOD_NOT_FOUND, f"Method '{method}' not supported.")

        except json.JSONDecodeError:
            logging.error(f"Failed to decode JSON: {line.strip()}")
            # Cannot reply if JSON is invalid and we can't get an ID
            continue
        except Exception as e:
            logging.exception("An unexpected error occurred during request handling.")
            # Try to send an internal error if we have an ID
            request_id = request.get("id") if 'request' in locals() else None
            if request_id is not None:
                send_error(request_id, ERROR_INTERNAL, f"An internal server error occurred: {e}")

if __name__ == "__main__":
    main()

6. Defining and Implementing the get_cwd Tool

The code above already includes the logic:

• handle_list_tools: This function responds to the ListTools request. It returns a list containing the definition of our get_cwd tool, including its name, description, and an empty input schema (since it takes no arguments).
• handle_call_tool: This function responds to CallTool requests. It checks if the requested tool name is get_cwd. If it is, it calls os.getcwd() to get the directory and sends it back in a structured success response. If the tool name doesn’t match, it sends a MethodNotFound error.

7. Making the Script Executable

On Linux and macOS, make the script directly executable:

1

chmod +x main.py

This allows the system to run the script using the interpreter specified in the shebang (#!/usr/bin/env python). Windows doesn’t use the shebang or executable bits in the same way; you’ll rely on the MCP client configuration to call the Python interpreter directly.

8. Configuring the MCP Client

Now, you need to tell your MCP client (e.g., your AI assistant’s configuration) how to run this server. You’ll typically edit a JSON configuration file. The exact file depends on the client (e.g., cline_mcp_settings.json, claude_desktop_config.json). Add an entry like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "mcpServers": {
    // ... other servers might be here ...

    "python_cwd_server": {
      "command": "/full/path/to/your/project/python_cwd_server/.venv/bin/python",
      "args": ["/full/path/to/your/project/python_cwd_server/main.py"],
      "env": {},
      "disabled": false, // Ensure it's enabled
      "autoApprove": [] // Default security
    }
  }
}

CRITICAL:

• Replace /full/path/to/your/project/python_cwd_server/ with the absolute path to your project directory.
• The command must point to the Python interpreter inside your virtual environment (.venv/bin/python). Using the system Python might cause import errors if you add dependencies later.
• The args should contain the absolute path to your main.py script.

After saving the configuration, the MCP client should automatically detect and start your server when needed.

9. Running and Testing

With the server configured, you can test it using your MCP client. Try a prompt like:

“Use the python_cwd_server’s get_cwd tool.”

Or, more specifically if the client allows direct tool calls:

“Call the get_cwd tool from the python_cwd_server.”

If everything is set up correctly, the client should communicate with your script, and you should receive a response containing the working directory where main.py is running (which should be your python_cwd_server project directory).

Troubleshooting:

• Path Errors: Double-check the absolute paths in your MCP configuration file. Typos are common!
• Permissions: Ensure main.py is executable (chmod +x) on Linux/macOS.
• Python Errors: Check the logs or terminal output where the MCP client might report errors from your script. Add more logging statements in main.py if needed.
• Configuration Reload: Some MCP clients might require a restart or a specific action to reload their configuration after you edit the settings file.

10. Conclusion

Congratulations! You’ve built a basic MCP server in Python from scratch. While simple, this example demonstrates the core principles:

• Using stdio for communication.
• Exchanging JSON-RPC messages.
• Handling ListTools to advertise capabilities.
• Handling CallTool to execute actions.
• Configuring the client to launch and manage the server.

You can use this structure as a foundation for building more sophisticated MCP servers in Python, perhaps integrating external APIs, interacting with local databases, or wrapping complex command-line tools. The Model Context Protocol opens up exciting possibilities for making AI assistants more powerful and context-aware development partners.