Local MCP Server Tutorial

🚀 Tutorial on Creating a Local MCP Server

This is a guide on creating a local MCP server.

🚀 Quick Start

✨ Features

This guide provides a step-by-step process to create, implement, debug, publish, and run a local MCP server.

📦 Installation

Prerequisites

• Node.js (It is recommended to use v22)
• Claude Desktop or other MCP clients

💻 Usage Examples

Basic Usage

1. Project Creation

npx giget@latest gh:7nohe/local-mcp-server-tutorial my-mcp-server
cd my-mcp-server
npm install
git init
git branch -M main
git add .
git commit -m "Initial commit"

2. Building and Running TypeScript Code

Build and run the following content in src/index.ts:

#!/usr/bin/env node
async function main() {
  console.error("Hello, world!");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

npm run build
./dist/index.js
# Output: Hello, world!

⚠️ Important Note

Through the bin attribute setting in package.json, a symbolic link will be created under node_modules/.bin/, allowing you to run ./dist/index.js.

3. Installing Required Libraries

npm install @modelcontextprotocol/sdk zod

4. Implementing the MCP Server

#!/usr/bin/env node
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Create an MCP server instance
const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
  capabilities: {
    resources: {},
    tools: {},
  },
});

async function main() {
  const transport = new StdioServerTransport();
  // Resources

  // Resource definition that returns "Hello, world!"
  server.resource(
    "Greeting",
    "greeting://hello",
    (uri, { }) => {
      console.log(uri)
      return {
        contents: [
          {
            uri: uri.href,
            text: "Hello, world!",
          }
        ]
      }
    })

  // Implement dynamic resources using ResourceTemplate
  server.resource(
    "Greeting with name",
    new ResourceTemplate("greeting://hello/:name"),
    (uri, params) => {
      return {
        contents: [
          {
            uri: uri.href,
            text: `Hello, ${params.name}!`,
          }
        ]
      }
    })
  // Tools

  // Define a calculator tool
  server.tool("calculator", {
    add: (a: number, b: number) => a + b,
    subtract: (a: number, b: number) => a - b,
    multiply: (a: number, b: number) => a * b,
    divide: (a: number, b: number) => a / b,
  });
}

// Start the server
main().catch((error) => {
  console.error("Server failed to start:", error);
});

5. Debugging

Use the Inspector for debugging:

npx @modelcontextprotocol/inspector ./dist/index.js

Open http://127.0.0.1:6274 in your browser to view the responses of the defined resources and tools.

⚠️ Important Note

For convenience, you can run npm run watch, and the code will be automatically rebuilt every time it changes.

Next, verify in Claude Desktop. Open claude_desktop_config.json from Settings -> Developer -> Edit Config and set it as follows:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/<Absolute project path>/my-mcp-server/dist/index.js"
    }
  }
}

Save and restart Claude Desktop. A list should be displayed in the tool buttons. If you can select resources or prompts through the Attach from MCP button, it means the operation is successful.

6. Package Publishing

npm login
npm publish

⚠️ Important Note

By setting the name in package.json to @your-name/my-mcp-server, you can more clearly identify your own package.

⚠️ Important Note

Once an npm package is published, it is difficult to delete. Therefore, please operate with caution.

Additional Notes

• Set scripts.prepublishOnly in package.json to the build command so that it will be automatically built when running npm publish.
• By setting the bin attribute in package.json, it can be run as a CLI:

"bin": "./dist/index.js"

• By setting the files attribute in package.json, you can specify the files to be published:

"files": [
  "dist"
]

7. Running the Published MCP Server

Configure as follows in Claude Desktop:

"my-mcp-server": {
  "command": "npx",
  "args": [
    "@your-name/my-mcp-server@latest"
  ]
}

In this way, you can run the published MCP server through the command.