Boilerplate MCP Server: TypeScript CLI & LLM-Powered AI Development

Boilerplate MCP Server

A boilerplate Model Context Protocol (MCP) server implementation using TypeScript. This project demonstrates how to build a well-structured MCP server that exposes both tools and resources to AI applications like Claude Desktop. It serves as a starting point for developers building MCP-compatible servers with a focus on clean architecture, automated workflows, and easy deployment.

Core Features

• STDIO MCP Server : Designed for AI clients like Claude Desktop, providing tools and resources via the Model Context Protocol.
• CLI Support : Human-friendly command-line interface for the same functionality, making it easy to test and use directly.
• IP Address Lookup : Get details about any IP address or your current device's IP.
• Automated Release Management : GitHub Actions workflow for continuous integration, testing, and publishing to GitHub Packages.

Installation

Global Installation

You can install this package globally to use as a CLI tool:

npm install -g @aashari/boilerplate-mcp-server

After global installation, you can run the CLI commands directly:

# Get help
boilerplate-mcp-server --help

# Get current IP details
boilerplate-mcp-server get-ip-details

# Get details for a specific IP
boilerplate-mcp-server get-ip-details 8.8.8.8

Local Installation

For development or local use, clone the repository and install dependencies:

git clone https://github.com/aashari/boilerplate-mcp-server.git
cd boilerplate-mcp-server
npm install

Then run the development server:

npm run dev

Or build and start:

npm run build
npm start

Configuration Options for End Users

Before setting up with Claude Desktop or Cursor AI, you can configure the server. There are two recommended options for end users:

Option 1: Direct Configuration in Claude/Cursor

Pass your configuration directly in the Claude Desktop config or Cursor AI command:

{
  "mcpServers": {
    "aashari/boilerplate-mcp-server": {
      "command": "npx",
      "args": ["-y", "DEBUG=true", "IPAPI_API_TOKEN=your_token", "aashari/boilerplate-mcp-server"]
    }
  }
}

Option 2: Global Configuration File (Recommended)

1. Create a global configuration file at $HOME/.mcp/configs.json:

{
  "@aashari/boilerplate-mcp-server": {
    "environments": {
      "DEBUG": "true",
      "IPAPI_API_TOKEN": "your_token"
    }
  }
}

2. Then use a simplified configuration in Claude Desktop or Cursor AI:

{
  "mcpServers": {
    "aashari/boilerplate-mcp-server": {
      "command": "npx",
      "args": ["-y", "aashari/boilerplate-mcp-server"]
    }
  }
}

This approach keeps your configuration in one secure location and simplifies your AI assistant setup.

Available Configuration Options

• DEBUG : Set to true to enable debug logging.
• IPAPI_API_TOKEN : API token for the IP API service (if required).

Setting Up with Claude Desktop

To use this MCP server with Claude Desktop:

1. Open Claude Desktop Settings :

* Launch Claude Desktop
* Click on the settings icon (gear) in the top-right corner

2. Edit MCP Configuration :

* Click on "Edit Config" button
* This will open File Explorer/Finder with the `claude_desktop_config.json` file

3. Update Configuration File :

* Add one of the configuration options from above to the file
* Save the file

Example with global configuration file already set up:

    {
  "mcpServers": {
    "aashari/boilerplate-mcp-server": {
      "command": "npx",
      "args": ["-y", "aashari/boilerplate-mcp-server"]
    }
  }
}

4. Restart Claude Desktop :

* Close and reopen Claude Desktop to apply the changes

5. Verify Tool Availability :

* On the Claude home page, look for the hammer icon on the right side
* Click it to see available tools
* Ensure the `get-ip-details` tool is listed

6. Test the Tool :

* Try asking Claude: "give me my public IP" or "analyze this IP: 8.8.8.8"
* Claude will use the MCP tool to fetch and display the requested information

Setting Up with Cursor AI

To use this MCP server with Cursor AI:

1. Open Cursor Settings :

* Launch Cursor
* Press `CMD + SHIFT + P` (or `CTRL + SHIFT + P` on Windows)
* Type "settings" and select "Cursor Settings"
* On the sidebar, select "MCP"

2. Add New MCP Server :

* Click "+ Add new MCP server"
* A configuration form will appear

3. Configure MCP Server :

* **Name** : Enter `aashari/boilerplate-mcp-server`
* **Type** : Select `command` from the dropdown
* **Command** : Choose one of the following based on your configuration approach:

If using global configuration file (recommended):

    npx -y aashari/boilerplate-mcp-server

If passing configuration directly:

    DEBUG=true IPAPI_API_TOKEN=your_token npx -y aashari/boilerplate-mcp-server


* Click "Add"

4. Verify Server Configuration :

* The server should now be listed with a green indicator
* You should see the `get_ip_details` tool listed under the server

5. Test the Tool :

* In the chat sidebar, ensure Agent mode is active
* Try asking: "give me my public IP" or "analyze this IP: 8.8.8.8"
* Cursor AI will use the MCP tool to fetch and display the requested information

Using as a CLI Tool

The package can also be used as a command-line tool for human interaction:

• Get help and available commands :

  npx -y aashari/boilerplate-mcp-server --help
  

Example output:

    Usage: @aashari/boilerplate-mcp-server [options] [command]

A boilerplate Model Context Protocol (MCP) server implementation using TypeScript

Options:
  -V, --version               output the version number
  -h, --help                  display help for command

Commands:
  get-ip-details [ipAddress]  Get details about a specific IP address or the current device
  help [command]              display help for command

• Get current device IP details :

  npx -y aashari/boilerplate-mcp-server get-ip-details
  

Example output:

    status: success
country: Indonesia
countryCode: ID
region: JK
regionName: Jakarta
city: Jakarta
zip: 11730
lat: -6.2114
lon: 106.8446
timezone: Asia/Jakarta
isp: Biznet Wifi
org:
as: AS17451 BIZNET NETWORKS
query: 118.99.106.135


* **Get details for a specific IP address** :

    npx -y aashari/boilerplate-mcp-server get-ip-details 8.8.8.8

Example output:

    status: success
country: United States
countryCode: US
region: VA
regionName: Virginia
city: Ashburn
zip: 20149
lat: 39.03
lon: -77.5
timezone: America/New_York
isp: Google LLC
org: Google Public DNS
as: AS15169 Google LLC
query: 8.8.8.8

---

About MCP

For detailed information about the Model Context Protocol (MCP), including core concepts, architecture, and implementation guides, please refer to the official MCP documentation.

For Developers

If you're interested in developing or extending this project, please refer to the Development Guide for detailed information on:

• Prerequisites and installation
• Project structure
• Configuration system
• Adding your own functionality
• Testing and deployment
• Creating your own MCP server
• And more

License

ISC