Quickstart Guide

Get Your First MCP Server Running

This guide will walk you through setting up, building, and testing your first MCP server. We’ll use the TypeScript Game of Thrones quotes server as our example, but you can follow similar steps for Python or Go.

By the end of this guide, you’ll have a working MCP server that can fetch quotes, perform calculations, and respond to prompts.

Prerequisites

Before you begin, make sure you have:

Node.js

Version 18 or higher for TypeScript examples

Python

Version 3.10 or higher for Python examples

Git

To clone the course repository

Code Editor

VS Code, Cursor, or your preferred editor

Step-by-Step Tutorial

Clone the Repository

First, clone the MCP Course repository to get access to all the example code:

git clone https://github.com/alexyslozada/mcp-course.git
cd mcp-course

The repository structure looks like this:

mcp-course/
├── servers/           # MCP server implementations
│   ├── basic/         # TypeScript: Game of Thrones quotes
│   ├── calculator-py/ # Python: Calculator operations
│   └── todo-ts/       # TypeScript: Todo management
└── clients/           # MCP client implementations
    ├── basic-ts/      # TypeScript client
    └── basic-py/      # Python client

Each server directory contains a complete, working example you can learn from and modify.

Navigate to the Server Directory

Let’s start with the TypeScript server that includes multiple features:

cd servers/basic

Take a look at the package.json to see the dependencies:

{
  "name": "basic",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.7.0",
    "@types/node": "^22.13.13",
    "node-fetch": "^3.3.2",
    "typescript": "^5.8.2"
  },
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  }
}

The key dependency is @modelcontextprotocol/sdk, which provides all the MCP functionality.

Install Dependencies

Install the required packages:

npm install

This will install:

The official MCP SDK for TypeScript
Zod for schema validation
Node-fetch for API calls
TypeScript compiler

Make sure you’re using Node.js 18 or higher. Check with node --version.

Build the Server

Compile the TypeScript code to JavaScript:

npm run build

This creates a dist/ directory with the compiled JavaScript files. You should see output like:

> [email protected] build
> tsc

If the build succeeds, you’re ready to run the server!

Understand the Server Code

Before running the server, let’s look at what it does. Open src/server.ts:

// Define a tool that fetches random quotes
server.tool(
  "get_random_quotes",
  { count: z.number().optional().default(5) },
  async ({ count }) => {
    try {
      const quotes = await fetchRandomQuotes(count);
      const formattedQuotes = quotes.map(formatQuote);
      
      return {
        content: [{ 
          type: "text", 
          text: formattedQuotes.join("\n---\n") 
        }]
      };
    } catch (error) {
      return {
        content: [{ 
          type: "text", 
          text: `Error: ${error.message}` 
        }],
        isError: true
      };
    }
  }
);

This server exposes:

2 Tools: get_random_quotes and lcm (least common multiple)
2 Resources: Random quotes and person properties
2 Prompts: Game of Thrones analysis and code review

Run the Server

Start the MCP server:

npm start

The server is now running and waiting for connections via stdio (standard input/output).

MCP servers typically communicate through stdio, which means they don’t print anything to the console. They’re waiting for a client to connect and send requests.

To test the server, you’ll need to connect a client. Keep this terminal open and open a new one for the next step.

Connect a Client

In a new terminal, navigate to the TypeScript client:

cd clients/basic-ts
npm install

The client code shows how to connect to the server:

Client Connection

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create a transport that connects to the server
const transport = new StdioClientTransport({
  command: "node",
  args: ["path/to/server.js"]
});

// Create and connect the client
const client = new Client(
  {
    name: "basic-client",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {},
      resources: {},
      tools: {}
    }
  }
);

await client.connect(transport);

You’ll need to update the path in the client code to point to your compiled server. Change the path in src/index.ts to match your local setup.

Test the Server

Run the client to test all server capabilities:

npm start

You should see output showing:Available Tools:

{
  "tools": [
    {
      "name": "get_random_quotes",
      "description": "",
      "inputSchema": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "default": 5
          }
        }
      }
    },
    {
      "name": "lcm",
      "description": "Calculate the least common multiple of a list of numbers",
      "inputSchema": {
        "type": "object",
        "properties": {
          "numbers": {
            "type": "array",
            "items": { "type": "number" },
            "minItems": 2
          }
        }
      }
    }
  ]
}

Tool Execution Result:

{
  "content": [
    {
      "type": "text",
      "text": "The least common multiple is: 60"
    }
  ]
}

Resource Data:

{
  "contents": [
    {
      "uri": "got://quotes/random",
      "mimeType": "text/plain",
      "text": "Quote: \"Winter is coming\"\nCharacter: Ned Stark\nHouse: House Stark\n---\n..."
    }
  ]
}

The client code demonstrates all MCP operations: listing capabilities, calling tools, reading resources, and getting prompts.

Try Other Examples

Now that you have the basic server running, try the other examples:

cd servers/calculator-py
pip install mcp
python server.py

Python Calculator Server

The Python example uses FastMCP for a simpler API:

Python Server Example

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Calculator MCP Server")

@mcp.tool()
def calculate(a: float, b: float, operation: str) -> float:
    if operation == "add":
        return float(a + b)
    elif operation == "subtract":
        return float(a - b)
    elif operation == "multiply":
        return float(a * b)
    elif operation == "divide":
        if b == 0:
            raise ValueError("No se puede dividir por cero")
        return float(a / b)
    else:
        raise ValueError("Operación no válida")

if __name__ == "__main__":
    mcp.run(transport='stdio')

Test it with the Python client:

cd clients/basic-py
python main.py

What’s Next?

Now that you have a working MCP server, you can:

Learn the Protocol

Understand how MCP works under the hood

Build Custom Tools

Create your own tools for specific use cases

Explore Examples

Deep dive into the server implementations

Integrate with LLMs

Connect your server to Ollama or Claude

Troubleshooting

Server doesn't start

Check Node.js version: Make sure you’re using Node.js 18 or higher

node --version

Check TypeScript compilation: Look for errors in the build step

npm run build

Verify dependencies: Reinstall packages if needed

rm -rf node_modules package-lock.json
npm install

Client can't connect

Update the server path: Make sure the client points to the correct server locationIn clients/basic-ts/src/index.ts, update:

const transport = new StdioClientTransport({
  command: "node",
  args: ["/absolute/path/to/servers/basic/dist/server.js"]
});

Check server is running: The server must be compiled and the path must exist

Import errors in TypeScript

Check package.json type: Make sure "type": "module" is setUse .js extensions: Import statements need .js even for TypeScript files:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

This is required for ES modules in TypeScript.

Python import errors

Install MCP SDK: Make sure the package is installed

pip install mcp

Check Python version: Use Python 3.10 or higher

python --version

Use virtual environment: Recommended for isolation

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install mcp

Still having issues? Check the GitHub repository for the latest code and examples.

Get Started

Core Concepts

Server Implementations

Client Implementations

Integrations

Get Your First MCP Server Running

Prerequisites

Node.js

Python

Git

Code Editor

Step-by-Step Tutorial

Try Other Examples

Python Calculator Server

What’s Next?

Learn the Protocol

Build Custom Tools

Explore Examples

Integrate with LLMs

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Server Implementations

Client Implementations

Integrations

​Get Your First MCP Server Running

​Prerequisites

Node.js

Python

Git

Code Editor

​Step-by-Step Tutorial

​Try Other Examples

​Python Calculator Server

​What’s Next?

Learn the Protocol

Build Custom Tools

Explore Examples

Integrate with LLMs

​Troubleshooting

Build docs developers (and LLMs) love

Get Your First MCP Server Running

Prerequisites

Step-by-Step Tutorial

Try Other Examples

Python Calculator Server

What’s Next?

Troubleshooting