Labsco
brunorozendo logo

Java MCP Filesystem Server

★ 1

from brunorozendo

A secure Java-based MCP server that provides controlled filesystem access to AI assistants.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#devops#git#security

Java MCP Filesystem Server

A Model Context Protocol (MCP) server implementation in Java that provides filesystem access to AI assistants. This multi-module project offers three different transport mechanisms (stdio, HTTP, SSE) all sharing common business logic for file operations.

Features

Multiple Transport Options

  • stdio: Standalone application for command-line integration (Claude Desktop, etc.)
  • HTTP: Servlet-based implementation for HTTP communication
  • SSE: Server-Sent Events servlet for real-time streaming

Comprehensive File Operations

The server exposes 10 MCP tools for filesystem manipulation:

  • read_file: Read the complete contents of a single file
  • read_multiple_files: Efficiently read multiple files in one operation
  • write_file: Create new files or overwrite existing ones
  • edit_file: Make line-based edits with diff preview support
  • create_directory: Create single or nested directory structures
  • list_directory: List contents of a directory with type indicators
  • directory_tree: Get a recursive JSON tree view of directories
  • move_file: Move or rename files and directories
  • search_files: Recursively search for files matching glob patterns
  • get_file_info: Retrieve detailed file metadata (size, timestamps, permissions)

Building from Source

  1. Clone the repository:
Copy & paste — that's it
git clone <repository-url>
cd mcp-server-filesystem
  1. Build all modules:
Copy & paste — that's it
./gradlew clean build

This creates the following artifacts:

  • stdio: stdio/build/libs/stdio-1.0.0.jar - Standalone application JAR
  • http: http/build/libs/http-1.0.0.war - HTTP servlet WAR file
  • sse: sse/build/libs/sse-1.0.0.war - SSE servlet WAR file
  • tools: tools/build/libs/tools-1.0.0.jar - Shared library JAR
  1. Build individual modules:
Copy & paste — that's it
./gradlew :stdio:build
./gradlew :http:build
./gradlew :sse:build
  1. Build native executable (optional, requires GraalVM):
Copy & paste — that's it
./gradlew :stdio:nativeCompile

The native executable will be created at stdio/build/native/nativeCompile/mcp-server-filesystem and offers faster startup times and lower memory footprint.

Security Considerations

IMPORTANT: This implementation has no path validation or directory restrictions. All filesystem operations are unrestricted and limited only by the permissions of the user running the server.

  1. No Path Restrictions: File operations can access any path the user has permissions for
  2. User Permissions: The server runs with the same permissions as the user who starts it
  3. Production Use: Consider implementing path validation before deploying in production environments

Note: Tool schema descriptions reference "allowed directories" but this feature does not exist in the current implementation.

Tool Examples

Reading a File

Copy & paste — that's it
{
  "tool": "read_file",
  "parameters": {
    "path": "/Users/myuser/documents/example.txt"
  }
}

Editing a File with Preview

Copy & paste — that's it
{
  "tool": "edit_file",
  "parameters": {
    "path": "/Users/myuser/documents/example.txt",
    "edits": [
      {
        "oldText": "Hello World",
        "newText": "Hello MCP"
      }
    ],
    "dryRun": true
  }
}

Searching for Files

Copy & paste — that's it
{
  "tool": "search_files",
  "parameters": {
    "path": "/Users/myuser/projects",
    "pattern": "*.java",
    "excludePatterns": ["**/build/**", "**/target/**"]
  }
}

Version History

  • 1.0.0 - Multi-module architecture with stdio, HTTP, and SSE transports
  • 0.7.2 - Previous version with single module implementation

Contributing

Contributions are welcome! Please ensure:

  1. Code follows Java naming conventions
  2. New tools are added to the shared tools module
  3. Tool schemas are properly defined in ToolSchemas.java
  4. Changes are tested with an MCP client
  5. Tests are written using Spock Framework in the tools module

License

[Specify your license here]

Author

Bruno Rozendo

Acknowledgments