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)

Requirements

• Java 25
• Gradle 9.x (for building from source)
• Servlet container (Tomcat, Jetty, etc.) for HTTP/SSE modules
• GraalVM (optional, for native image compilation)

Building from Source

1. Clone the repository:

git clone <repository-url>
cd mcp-server-filesystem

2. Build all modules:

./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

3. Build individual modules:

./gradlew :stdio:build
./gradlew :http:build
./gradlew :sse:build

4. Build native executable (optional, requires GraalVM):

./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.

Usage

Option 1: stdio Transport (Standalone)

The stdio transport uses stdin/stdout for communication.

java -jar stdio/build/libs/stdio-1.0.0.jar

Or run the native executable (if built with GraalVM):

./stdio/build/native/nativeCompile/mcp-server-filesystem

Configuring with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/stdio-1.0.0.jar"
      ]
    }
  }
}

Option 2: HTTP Transport (Servlet)

1. Deploy the WAR file to your servlet container:

cp http/build/libs/http-1.0.0.war $TOMCAT_HOME/webapps/

2. The HTTP endpoint will be available at:

http://localhost:8080/v1/mcp

3. Setup tomcat server.xml

<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
    <Context path="/v1" docBase="http-1.0.0.war" reloadable="true" />
</Host>

Option 3: SSE Transport (Servlet)

1. Deploy the WAR file to your servlet container:

cp sse/build/libs/sse-1.0.0.war $TOMCAT_HOME/webapps/

2. The SSE endpoints will be available at:

SSE endpoint: http://localhost:8080/v2/sse
Messages endpoint: http://localhost:8080/v2/messages

3. Setup tomcat server.xml

<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
    <Context path="/v2" docBase="sse-1.0.0.war" reloadable="true" />
</Host>

Development Commands

# Run all tests
./gradlew test

# Run tests for tools module
./gradlew :tools:test

# Build without tests
./gradlew build -x test

# Generate test coverage report
./gradlew :tools:test jacocoTestReport

Key Dependencies

• io.modelcontextprotocol.sdk:mcp:0.15.0 - MCP SDK for Java
• jakarta.servlet:jakarta.servlet-api:6.1.0 - Servlet API
• io.github.java-diff-utils:java-diff-utils:4.12 - Diff generation for edit operations
• com.fasterxml.jackson.core:jackson-databind:2.19.1 - JSON processing
• Spock Framework 2.4-M6-groovy-4.0 - Testing

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

{
  "tool": "read_file",
  "parameters": {
    "path": "/Users/myuser/documents/example.txt"
  }
}

Editing a File with Preview

{
  "tool": "edit_file",
  "parameters": {
    "path": "/Users/myuser/documents/example.txt",
    "edits": [
      {
        "oldText": "Hello World",
        "newText": "Hello MCP"
      }
    ],
    "dryRun": true
  }
}

Searching for Files

{
  "tool": "search_files",
  "parameters": {
    "path": "/Users/myuser/projects",
    "pattern": "*.java",
    "excludePatterns": ["**/build/**", "**/target/**"]
  }
}

Troubleshooting

Common Issues

1. Server won't start: Verify Java 25 is installed and in your PATH
2. WAR deployment fails: Ensure your servlet container supports Jakarta Servlet API 6.1 3Permission errors: The server can only access files the running user has permissions for

Debugging

Check application logs (stdout/stderr for stdio, container logs for HTTP/SSE) for error messages.

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

• Built with the Model Context Protocol SDK for Java
• Inspired by the TypeScript reference implementation