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.

- 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

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)

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

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

- 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

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

- Build native executable (optional, requires GraalVM):

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

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

Add to yourclaude_desktop_config.json:

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

- Deploy the WAR file to your servlet container:

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

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

- Deploy the WAR file to your servlet container:

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

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

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

# 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

- 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

IMPORTANT: This implementation hasno path validationor directory restrictions. All filesystem operations are unrestricted and limited only by the permissions of the user running the server.
- No Path Restrictions: File operations can access any path the user has permissions for
- User Permissions: The server runs with the same permissions as the user who starts it
- 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": "read_file", "parameters": { "path": "/Users/myuser/documents/example.txt" } }

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

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

- Server won't start: Verify Java 25 is installed and in your PATH
- 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

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

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

Contributions are welcome! Please ensure:
- Code follows Java naming conventions
- New tools are added to the sharedtoolsmodule
- Tool schemas are properly defined inToolSchemas.java
- Changes are tested with an MCP client
- Tests are written using Spock Framework in thetoolsmodule

- Built with theModel Context Protocol SDKfor Java
- Inspired by the TypeScript reference implementation

A server for programmatic exploration of local files and folders.