🟢 MCP Server in Node.js

!MCP Server in Node.js banner

Build and run a custom MCP Server in Node.js in just 2 minutes ⏱️

Overview · Features · Installation · Testing with MCP Inspector · Setting Environment Variables for Testing · Integrating with Cursor AI · Using the MCP Tool in Cursor (Agent Mode) · Code Overview · What is MCP? · References & Resources · License

Overview

MCP (Model Context Protocol) is a framework that allows you to integrate custom tools into AI-assisted development environments—such as Cursor AI. MCP servers expose functionality (like data retrieval or code analysis) so that an LLM-based IDE can call these tools on demand. Learn more about MCP in the Model Context Protocol Introduction.

This project demonstrates an MCP server implemented in JavaScript using Node.js. It defines two tools: add, which takes two numeric inputs and returns their sum, and getApiKey, which retrieves the API key from the API_KEY environment variable.

Requirements

• Node.js: Version 20 or higher is required.

Features

• MCP Integration: Exposes tool functionality to LLM-based IDEs.
• Addition Tool: Accepts two numeric parameters and returns their sum.
• Env Var Retrieval: Demonstrates how to load an example environment variable from the configuration file.
• Input Validation: Uses Zod for schema validation.
• Standard I/O Transport: Connects via StdioServerTransport for integration with development environments.

Installation

1. Clone the Repository

   git clone <repository_url>
   cd <repository_directory>
   

2. Install Dependencies

   You can install the project dependencies in one of two ways:

   Option 1: Install using the existing package.json

   Simply run:

   npm install
   

   Option 2: Install dependencies manually

   If you prefer, delete the existing package.json and install the required packages manually:

   npm install @modelcontextprotocol/sdk zod
   

   Then, update the newly generated package.json file to include the following lines, which enables ES Modules and adds the mcp inspector command:

   "type": "module",
   "scripts": {
    "inspector": "npx @modelcontextprotocol/inspector node ./mcp-server.js"
   }
   

Testing with MCP Inspector

The MCP Inspector is a debugging tool that lets you test your server's tools interactively before integrating with an IDE.

Option 1: Run directly with npx

npx @modelcontextprotocol/inspector node ./mcp-server.js

Option 2: Use the npm script

npm run inspector

This will:

1. Start the MCP inspector server
2. Open your browser to the inspector interface
3. Allow you to test tools, resources, and prompts

Open the MCP Server Inspector on the browser: http://localhost:6274/

Setting Environment Variables for Testing

To test the getApiKey tool with different API keys, you can set environment variables before running the inspector:

Linux/macOS (Bash/Zsh):

# Temporary (current session only)
export API_KEY="your-test-key"
npm run inspector

# Or set for single command
API_KEY="your-test-key" npm run inspector

Windows (Command Prompt):

# Set for current session
set API_KEY=your-test-key
npm run inspector

Windows (PowerShell):

# Set for current session
$env:API_KEY="your-test-key"
npm run inspector

# Or set for single command
$env:API_KEY="your-test-key"; npm run inspector

Integrating with Cursor AI

To integrate this MCP server with Cursor IDE, you need to add the configuration through Cursor's settings interface:

1. Open Cursor IDE
2. Go to Settings → Tools & Integrations
3. Click on Add Custom MCP Server
4. Add the configuration below

Important: If you already have other MCP servers configured, don't overwrite the entire configuration. Instead, add the "MCP Server Boilerplate" object to the existing "mcpServers" object.

Sample Configuration File: This project includes a sample configuration file at ./cursor/mcp.json that you can reference or copy from.

Configuration Structure

Below is the configuration you need to add:

Linux/macOS example:

{
  "MCP Server Boilerplate": {
    "command": "node",
    "args": ["/home/john/mcp-server-node/mcp-server.js"],
    "env": {
      "API_KEY": "abc-1234567890"
    }
  }
}

Windows example:

{
  "MCP Server Boilerplate": {
    "command": "node",
    "args": ["C:\\Users\\john\\mcp-server-node\\mcp-server.js"],
    "env": {
      "API_KEY": "abc-1234567890"
    }
  }
}

If you have existing MCP servers configured, your full configuration might look like this:

{
  "mcpServers": {
    "existing-server": {
      "command": "python",
      "args": ["/path/to/existing/server.py"]
    },
    "MCP Server Boilerplate": {
      "command": "node",
      "args": ["/home/john/mcp-server-node/mcp-server.js"],
      "env": {
        "API_KEY": "abc-1234567890"
      }
    }
  }
}

Configuration Parameters

• MCP Server Boilerplate:
  This is the key for your server configuration. You can name it as you like.

• command:
  The Node.js executable to run your server. You can use either:

  • "node" (if Node.js is in your PATH)
  • The full path to your Node.js executable (if needed)

  Finding your Node.js path:

  Linux/macOS:

  which node
  # Example output: /home/john/.nvm/versions/node/v20.13.1/bin/node
  

  Windows (Command Prompt):

  where node
  # Example output: C:\Program Files\nodejs\node.exe
  

  Windows (PowerShell):

  Get-Command node
  # Example output: C:\Program Files\nodejs\node.exe
  

• args:
  An array containing the absolute path to your MCP server file.

  Linux/macOS examples:

  ["/home/john/mcp-server-node/mcp-server.js"]
  

  Windows examples:

  ["C:\\Users\\john\\mcp-server-node\\mcp-server.js"]
  

• env: (Optional)
  Defines environment variables for your MCP server process. In this example, the API_KEY is set to "abc-1234567890". Adjust this value as needed for your environment.

Using the MCP Tool in Cursor (Agent Mode)

With the MCP server integrated into Cursor IDE and with Agent mode enabled, simply use a natural language prompt like:

add 3 and 5

or

what is my API key?

The AI agent will infer the available add or getApiKey tool from your MCP server and execute it accordingly.

Code Overview

The project comprises the following key parts:

• MCP Server Initialization:
  The MCP server is instantiated using McpServer from the MCP SDK and connected via StdioServerTransport.

• Tool Definitions:

  • add:
    Defined with a Zod schema that accepts two numbers (a and b) and returns their sum as text.
  • getApiKey:
    Retrieves the API key from the environment variable API_KEY and returns it as text.

What is MCP?

Model Context Protocol (MCP) provides a standardized approach to integrate custom tools into AI-assisted development environments. With MCP, you can define tools that perform specific tasks—such as retrieving external data, validating code, or enforcing coding standards—and the AI assistant in your IDE can call these tools automatically based on context. This helps improve developer productivity, ensures consistent quality, and streamlines workflows.

References & Resources

• Model Context Protocol: typescript-sdk
• Use Your Own MCP on Cursor in 5 Minutes
• Model Context Protocol Introduction

License

This project is licensed under the MIT License.