Local File System and Command Execution for Claude Desktop

Overview

The Local File System and Command Execution for Claude Desktop project is a custom implementation of the Model Context Protocol (MCP) server. It provides tools for interacting with the local file system and executing commands, extending the capabilities of Claude Desktop and other Large Language Model (LLM) clients.

What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. It enables AI models to connect to various data sources and tools, much like a USB-C port standardizes device connections.

Key Benefits of MCP

• Standardized Integration: Pre-built integrations for LLMs.
• Vendor Flexibility: Compatible with multiple LLM providers (Claude, GPT-4o, Gemini, etc.).
• Security: Best practices for securing data within your infrastructure.
• Tool Exposure: Encapsulates existing tools for use with MCP-compatible LLM clients.

Features

The MCP server offers the following tools:

• execute_shell_command: Execute shell commands and retrieve results.
• show_file: View file contents with optional line range specification.
• search_in_file: Search for patterns in files using regular expressions.
• edit_file: Make precise changes to files with string replacements and line operations.
• write_file: Write or append content to files.
• fetch_page: Fetch web page contents and convert them to PDF or markdown.

MCP Architecture

MCP follows a client-server architecture:

• Hosts: LLM applications (e.g., Claude Desktop) that initiate connections.
• Clients: Maintain 1:1 connections with servers.
• Servers: Provide context, tools, and prompts to clients.

Prerequisites

• Python 3.10 or higher.
• An MCP-compatible client (e.g., Claude Desktop).

Installation

1. Install uv.
2. Clone the repository or download the source code.
3. Run uv run mcp install to install the MCP server.
4. Update your MCP server configuration in Claude Desktop with the absolute path to the uv executable.

Example configuration:

{
  "globalShortcut": "",
  "mcpServers": {
    "zbigniew-mcp": {
      "command": "/Users/zbigniewtomanek/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "marker-pdf",
        "mcp",
        "run",
        "/Users/zbigniewtomanek/PycharmProjects/my-mcp-tools/server.py"
      ]
    }
  }
}

Usage

Connecting from Claude Desktop

1. Open Claude Desktop.
2. Connect to the MCP server using the identifier "zbigniew-mcp".

Available Tools

execute_shell_command

Execute shell commands safely:

execute_shell_command(["ls", "-la"])
execute_shell_command(["grep", "-r", "TODO", "./src"])

show_file

View file contents:

show_file("/path/to/file.txt")
show_file("/path/to/file.txt", num_lines=10)

search_in_file

Search for patterns in files:

search_in_file("/path/to/script.py", r"def\s+\w+\s*\(")

edit_file

Make precise changes to files:

edit_file("config.json", replacements={"\"debug\": false": "\"debug\": true"})

write_file

Write or append content to files:

write_file("/path/to/file.txt", "New content")
write_file("/path/to/log.txt", "Log entry", mode="a")

fetch_page

Fetch web page contents:

fetch_page("https://example.com")

Transport Mechanisms

MCP supports multiple transport methods:

• Standard Input/Output (stdio): Ideal for local processes.
• Server-Sent Events (SSE): Enables server-to-client streaming.

Extending with Your Own Tools

You can extend the MCP server by adding new tools with the @mcp.tool decorator. Follow the pattern in server.py to create new tools.

Related Projects

• langchain-mcp-adapters: Use MCP with LangChain.
• MCP-Bridge: Map MCP tools to OpenAI's format.

Security Considerations

The MCP server provides access to your local system. Be mindful of the following:

• Executes shell commands as your user.
• Can read, write, and modify files on your system.
• Consider limiting access to specific directories for security.

License

This project is licensed under the Apache-2.0 license.