Building Custom MCP Servers — A Beginner’s Guide to TypeScript & Python

Wouldn't it be convenient if you could connect your carefully organized notes or frequently used computer scripts directly to an AI assistant like Claude? Using the Model Context Protocol (MCP), the hottest topic in the AI ecosystem right now, you can quickly build a customized AI assistant for yourself without needing complex technical knowledge. Ready to start? Let’s learn how to build a custom server that seamlessly links your local computer data with AI in an easy and fun way.

Why do you need your own custom server?

Using various MCP servers already available online is a great starting point. Simply connecting a Brave Search server for real-time web searches or a tool to read folders on your computer can significantly enhance Claude's utility.

However, the real magic happens when you start dealing with 'your own data.' The moment you connect your private, hand-written diary, a company-specific database, or your frequently used Python automation scripts to Claude, you create a one-of-a-kind, hyper-personalized assistant.

Don't feel intimidated by the idea of building a server. You don't need deep knowledge of complex network backends. With just a few lines of code, you can quickly build a robust bridge that securely connects your local environment to Claude.

Implementation with TypeScript: The Streamlined v2 SDK

First, let's look at a tool that is a staple of the web ecosystem: TypeScript.

The recently released TypeScript SDK v2 has done away with complex setup processes and has been reborn to be very intuitive. Now, you only need the @modelcontextprotocol/server object and the McpServer helper from the serveStdio package to launch a custom server in just a few lines.

Shall we look at a basic weather information server example written using the TypeScript SDK v2?

// TypeScript SDK v2 기준
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

const server = new McpServer({
  name: "my-weather-server",
  version: "1.0.0"
});

// 도구 등록하기
server.registerTool(
  "get-weather",
  {
    description: "특정 지역의 날씨 정보를 가져옵니다.",
    inputSchema: z.object({
      location: z.string().describe("날씨를 조회할 도시 이름 (예: 서울, 부산)")
    })
  },
  async ({ location }) => {
    return {
      content: [{ type: "text", text: `${location}의 현재 날씨는 맑음입니다.` }]
    };
  }
);

// stdio 방식으로 서버 실행
serveStdio(() => server);

There is one critical pitfall that beginner developers often encounter when running this code: standard output noise.

Programs like Claude Desktop communicate with the MCP servers we build via a virtual connection called standard input/output (stdio). Think of this connection as a clean, private telephone line designed solely for specific JSON-RPC data.

So, what happens if you carelessly leave a console.log in your code for debugging? Doing this is like suddenly shouting noise into that private phone line. Claude will experience a communication error due to the unexpected text, ultimately causing the connection to drop.

Therefore, when you want to observe operations inside an MCP server, you must always use console.error. This command sends messages through a separate backup channel known as standard error, allowing you to monitor logs safely without introducing any noise into your private communication line.

Implementation with Python: The Magic of a Single Decorator

If Python is your weapon of choice, you can build custom servers even more easily and simply using the FastMCP interface in the new Python SDK v2. Instead of complex configuration code, you just add one decorator above the functions you normally write, and you're all set.

As long as you properly use Python's standard type hints and docstrings, the @mcp.tool() decorator automatically reads them and converts them into a JSON schema that Claude can understand. Let's see how to implement this with a simple example.

python

# Python SDK v2 (FastMCP) 기준 예시
from mcp.server.fastmcp import FastMCP

# FastMCP 서버 인스턴스 생성
mcp = FastMCP("My Custom Server")

@mcp.tool()
def calculate_shipping(weight: float, zone: str) -> str:
    """배송 요금을 계산하는 도구입니다."""
    # print()는 통신을 방해하므로 사용하지 않고, 로깅 라이브러리를 사용해 출력합니다.
    price = weight * (1.5 if zone == "US" else 2.5)
    return f"배송료: ${price:.2f}"

There is one important secret you must remember: you must never use the print() function you might habitually use in your code. If the output from print() contaminates the dedicated channel through which the AI and server exchange data, the communication connection will be cut off. When you need to leave logs or debugging messages, it is safe to use the Python standard library's logging system to output to standard error.

The development and registration process has also become incredibly convenient. Running the mcp dev server.py command in your terminal will automatically apply changes in real-time as you modify your code, and you can test the connection status immediately in the web dashboard (MCP Inspector UI) that opens on port 6274. Once development is finished, you can enter the mcp install server.py command to register your server with the Claude Desktop app in one go, without having to navigate through complex paths.

Connecting Your Own Server to Claude Desktop

Once you have finished your custom server code, it is time to connect it to Claude Desktop running on your computer. The setup process is much simpler than you might think. You just need to specify how to run your server in the Claude Desktop configuration file, claude_desktop_config.json.

First, you need to find and open this configuration file. Depending on your operating system, try navigating to the following paths:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

If the file doesn't exist in that folder, you can open a text editor and create it yourself. Once you have the file open, register the server you built earlier as shown below. Note that the path to the script file must be an absolute path for it to be recognized without errors.

json

{
  "mcpServers": {
    "my-python-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp",
        "python",
        "/Users/username/mcp-server/server.py"
      ]
    }
  }
}

The configuration above is an example using the uv run method, which is the fastest and safest way to run a Python server. It is a concise technique that automatically fetches and runs necessary packages without the hassle of manually creating virtual environments or pre-installing dependencies. If you want to register a TypeScript server, you can configure the command as npx -y tsx /절대경로/server.ts to connect it immediately without a build step.

Once you have finished the setup, restart the Claude Desktop app. If you see a plug icon appear in the bottom right of your chat window, you are ready to go.

Preparing for the Agent Era with Your Own Weapons

AI has evolved beyond a mere assistant that follows simple instructions; it has become a smart partner that we can teach how to do our work. If you have TypeScript or Python code you use often, don't hesitate—build your first MCP server. As you add more tools tailored to your workflow, you'll experience the thrill of working with your own custom-built agent!