Localutils MCP Server

🚀 Local Utility MCP Server

A Model Context Protocol (MCP) server that provides access to various local system utilities. This server can be used with Cursor and other compatible MCP clients to quickly access system information.

🚀 Quick Start

This MCP server offers a range of local system utilities, enabling seamless access to system information when used with Cursor and other MCP clients.

✨ Features

The utilities provided by this server include:

• Time and Date: Retrieve the current local time and date, including the day of the week, in various formats.
• Hostname: Obtain the hostname of the system.
• Public IP Address: Get the public IP address of the machine.
• Directory Listing: List the contents of a specified directory.
• Node.js Version: Retrieve information about the running Node.js version.
• Port Checker: Check the processes running on a specific port.
• Thought Tool: Record, retrieve, and analyze thoughts during development sessions.

📦 Installation

Global Installation

pnpm add -g localutils-mcp-server

Run with npx

You can also use npx to run the server directly without global installation:

npx localutils-mcp-server

💻 Usage Examples

Start the Server

If globally installed:

localutils-mcp

Using npx:

npx localutils-mcp-server

Use with Cursor

You can use this server by configuring the MCP server in Cursor's settings.

1. Open Cursor settings.
2. Navigate to the MCP section.
3. Add a new MCP server with the following configuration:

{
    "name": "localutils",
    "command": "npx",
    "args": ["localutils-mcp-server"]
}

Use the MCP Inspector

You can test the server by running the following command:

pnpm run inspector

This will start the MCP inspector at http://localhost:5173.

Available Tools

get_time_and_date

Returns the current local time and date in various formats, including:

• Local time
• Local date
• Day of the week
• ISO 8601 format
• Unix timestamp

get_hostname

Returns the hostname of the machine running the MCP server.

get_public_ip

Returns the public IP address of the machine running the MCP server.

list_directory

Lists the contents of a specified directory.

Parameters:

• path (string, required): The path of the directory whose contents are to be listed.

get_node_version

Returns information about the Node.js version in the environment where the MCP server is running.

check_port

Checks the processes running on a specific port.

Parameters:

• port (number, required): The port number to check.

record_thought

Records a thought.

Parameters:

• thought (string, required): The thought to be recorded.
• metadata (object, optional): An object containing additional metadata, such as context information.

retrieve_thoughts

Retrieves all recorded thoughts.

delete_thought

Deletes a thought with a specified ID.

Parameters:

• id (string, required): The unique identifier of the thought to be deleted.

Development

Build

pnpm run build

Run in Development Mode

pnpm run dev

Test

pnpm test

Git Workflow

This repository includes a pre - commit hook that automatically builds the server before each commit. This ensures that the build files are always in sync with the repository.

The build files are included in the git repository to facilitate the use of npx without prior building.

To set up the pre - commit hook, run the following after cloning the repository:

pnpm install

This will install the dependencies and set up the pre - commit hook using Husky.

📄 License

MIT