Quick Start

This guide will walk you through the fastest way to get a new MCP server running on your local machine. By the end, you’ll have a deployed, testable service.

Prerequisites

Before you begin, make sure you have the following tools installed on your system:

DFX: The DFINITY Canister SDK. Installation Guide.
Node.js: Version 18.0 or higher. Download.
MOPS: The Motoko Package Manager. Installation Guide.
Git: The version control system. Download.

Step 1: Scaffold Your Project

First, create a new project using our template. This sets up a complete, ready-to-run MCP server.

# Creates a new project in a directory called `my-mcp-server`
npx create-motoko-mcp-server my-mcp-server

# Navigate into your new project directory
cd my-mcp-server

Step 2: Initialize Your Repository

The Prometheus publishing process is tied to your Git history. Initialize a repository and make your first commit now so you’re ready to publish later.

# Initialize a new Git repository
git init

# Stage all the new files
git add .

# Make your first commit
git commit -m "Initial commit from template"

Step 3: Install Dependencies

Next, you need to install the project’s dependencies. The template uses both Node.js for scripting and MOPS for Motoko packages. Run the following commands from your project’s root directory:

# Install Node.js dependencies
npm install

# Install Motoko dependencies
npm run mops:install

Step 4: Deploy Your Server

Now, you’ll deploy the server to a local, simulated version of the blockchain network.

Start the Local Replica: This command starts the local development network in the background.
If you already have the local replica running from another project, you can skip this step. You can check its status by running dfx ping in your terminal. If it returns a healthy status, you’re good to go.
npm run start
Deploy to the Local Replica: This command compiles your Motoko code and deploys it to the local network.
You must run this command in a new terminal window, as the local replica will be running in your current one.
npm run deploy
After a moment, the CLI will output the canister ID of your deployed server. Keep this ID handy for the next step.

Step 5: Test with the MCP Inspector

The MCP Inspector is a web-based tool for interacting with your server’s tools.

Launch the Inspector: This command starts the Inspector web app.
npm run inspector
Connect to Your Server: The Inspector needs the URL of your local server. Construct the URL using the canister ID from the deploy step.
# Replace `your_canister_id` with the actual ID from the deploy output http://127.0.0.1:4943/mcp/?canisterId=your_canister_id
Paste this URL into the Inspector’s connection bar. You can now see and call the default get_weather tool.

🎉 Congratulations! You have a working MCP server running locally. The next sections cover advanced topics like adding authentication and connecting to the payments system.

Getting Started

Guides

Reference

Prerequisites

Step 1: Scaffold Your Project

Step 2: Initialize Your Repository

Step 3: Install Dependencies

Step 4: Deploy Your Server

Step 5: Test with the MCP Inspector

​Prerequisites

​Step 1: Scaffold Your Project

​Step 2: Initialize Your Repository

​Step 3: Install Dependencies

​Step 4: Deploy Your Server

​Step 5: Test with the MCP Inspector

Prerequisites

Step 1: Scaffold Your Project

Step 2: Initialize Your Repository

Step 3: Install Dependencies

Step 4: Deploy Your Server

Step 5: Test with the MCP Inspector