{"id":30088319,"url":"https://github.com/redis/redis-mcp-java","last_synced_at":"2026-03-10T04:31:40.473Z","repository":{"id":303765899,"uuid":"1016607961","full_name":"redis/redis-mcp-java","owner":"redis","description":"Redis MCP library for Java","archived":false,"fork":false,"pushed_at":"2025-07-16T06:46:28.000Z","size":95,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-07T17:58:25.545Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-09T09:02:59.000Z","updated_at":"2025-07-16T08:44:36.000Z","dependencies_parsed_at":"2025-07-09T10:27:50.024Z","dependency_job_id":"de2ef632-58cf-472e-8902-97ef367ccc4b","html_url":"https://github.com/redis/redis-mcp-java","commit_stats":null,"previous_names":["bobymicroby/redis-mcp-java"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/redis/redis-mcp-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redis%2Fredis-mcp-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redis%2Fredis-mcp-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redis%2Fredis-mcp-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redis%2Fredis-mcp-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redis","download_url":"https://codeload.github.com/redis/redis-mcp-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redis%2Fredis-mcp-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30324398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T01:36:58.598Z","status":"online","status_checked_at":"2026-03-10T02:00:06.579Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-09T04:28:45.507Z","updated_at":"2026-03-10T04:31:40.463Z","avatar_url":"https://github.com/redis.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e ⚠️ **Beta Software**: This project is under active development. Expect bugs and breaking changes.\n\n\n\u003e For the official Redis MCP server, please visit [redis-mcp](https://github.com/redis/mcp-redis)\n\u003e This project is intended to be used as library to develop custom MCP tools for Redis ( e.g. in-house Redis modules,\n\u003e custom Lua scripts or Redis Functions )\n\u003e The existing tools are provided as examples and can be used as a reference for developing your own tools.\n\n# Redis MCP Java\n\nA Java implementation of Model Context Protocol (MCP) tools for Redis operations, providing both Lettuce and Jedis\nclient support with automatic tool discovery and schema generation.\n\n## Architecture Overview\n\nThe Redis MCP Java library follows a layered architecture that separates concerns between connection\nmanagement,validation, MCP tool handling, and MCP protocol integration.\n\n### Core Components\n\n```\nredis-mcp-java/\n├── core/                           # Core MCP Redis functionality\n│   └── src/main/java/io/redis/mcp/java/core/\n│       ├── handlers/               # Redis command implementations\n│       │   ├── lettuce/           # Lettuce-based handlers\n│       │   └── jedis/             # Jedis-based handlers\n│       ├── net/                   # Connection management\n│       ├── tooling/               # Tool discovery and MCP integration\n│       └── validation/            # Input validation and error handling\n└── spring/                        # Spring Boot integration (optional)\n```\n\n### Key Architectural Patterns\n\n#### 1. Handler-Based Tool Implementation\n\nEach Redis command is implemented as a separate handler class that extends either `LettuceHandler` or `JedisHandler`:\n\n```java\npublic class GetHandler extends LettuceHandler {\n    public record GetRequest(\n            @Nonnull @Description(\"The Redis key to retrieve\") String key\n    ) {\n    }\n\n    @Override\n    public McpSchema.Tool toolSchema() {\n        return new McpSchema.Tool(\n                \"redis_get\",\n                \"Retrieve a value from Redis by key\",\n                recordToJSONSchema(GetRequest.class)\n        );\n    }\n\n    // Implementation methods...\n}\n```\n\n#### 2. Automatic Tool Discovery\n\nThe `HandlerScanner` uses reflection to automatically discover and instantiate all handler classes:\n\n- Scans specified packages for `LettuceHandler` and `JedisHandler` subclasses\n- Instantiates handlers with Redis connection providers\n- Validates tool name uniqueness across all handlers\n- Builds tool registry for MCP server registration\n\n#### 3. Connection Management\n\nThe `Redis` interface abstracts connection management with support for:\n\n- **Lazy Connection Pooling**: Connections created on-demand\n- **Round-Robin Distribution**: Load balancing across pooled connections\n- **Dual Client Support**: Both Lettuce (async/reactive) and Jedis (sync) clients\n- **Connection Caching**: Efficient connection reuse\n\n#### 4. Schema Generation\n\nAutomatic MCP JSON Schema generation from Java records:\n\n- `@Description` annotations provide field documentation\n- `@Nonnull` annotations mark required fields\n\n#### 5. Validation\n\nType-safe user input validation\n\n- **Result\u003cT, E\u003e**: Represents success or failure without exceptions\n- **Validation Combinators**: Compose multiple validations\n- **Type Safety**: Compile-time validation of parameter types\n- **Error Accumulation**: Collect multiple validation errors\n\n## How to Add New MCP Tools\n\nAdding new Redis tools involves creating handler classes that integrate automatically with the MCP framework.\n\n### Step 1: Choose Your Client\n\nDecide whether to use Lettuce or Jedis :\n\n```java\n\npublic class MyHandler extends LettuceHandler {\n    // Implementation\n}\n\npublic class MyHandler extends JedisHandler {\n    // Implementation\n}\n```\n\n### Step 2: Define Request Schema\n\nCreate a Java record with validation annotations:\n\n```java\npublic record MyRequest(\n        @Nonnull\n        @Description(\"The Redis key to operate on\")\n        String key,\n\n        @Description(\"Optional timeout in seconds\")\n        Long timeout,\n\n        @Description(\"Operation mode\")\n        String mode\n) {\n}\n```\n\n### Step 3: Implement Tool Schema\n\nDefine the MCP tool specification:\n\n```java\n\n@Override\npublic McpSchema.Tool toolSchema() {\n    return new McpSchema.Tool(\n            \"redis_my_command\",                    // Tool name (must be unique)\n            \"Description of what this tool does\",  // Tool description\n            recordToJSONSchema(MyRequest.class)    // Auto-generated schema\n    );\n}\n```\n\n### Step 4: Add Input Validation\n\nUse the validation framework to safely parse arguments:\n\n```java\nprivate static Result\u003cMyRequest, McpSchema.CallToolResult\u003e validateRequest(\n        Map\u003cString, Object\u003e arguments\n) {\n    return Result.combine(\n            V.String(arguments, \"key\"),           // Required string\n            V.OptionalLong(arguments, \"timeout\"), // Optional long\n            V.OptionalString(arguments, \"mode\")   // Optional string\n    ).with(MyRequest::new);\n}\n```\n\n### Step 5: Implement Sync Handler\n\n```java\n\n@Override\npublic McpSchema.CallToolResult handleSync(\n        McpSyncServerExchange exchange,\n        Map\u003cString, Object\u003e arguments\n) {\n    var result = validateRequest(arguments);\n\n    if (result.isErr()) {\n        return result.unwrapErr();\n    }\n\n    var request = result.unwrap();\n\n    var jedis = getConnection();\n\n    var request = result.unwrap();\n    var value = jedis.myCommand(request.key);\n\n\n    return McpSchema.CallToolResult.builder()\n            .addTextContent(\"Result: \" + value)\n            .isError(false)\n            .build();\n}\n```\n\n### Step 6: Implement Async Handler\n\n```java\n\n@Override\npublic CompletableFuture\u003cMcpSchema.CallToolResult\u003e handleAsync(\n        McpAsyncServerExchange exchange,\n        Map\u003cString, Object\u003e arguments\n) {\n    var result = validateRequest(arguments);\n\n    if (result.isErr()) {\n        return CompletableFuture.completedFuture(result.unwrapErr());\n    }\n\n    var request = result.unwrap();\n\n    return getConnectionAsync()\n            .thenCompose(conn -\u003e conn.async().myCommand(request.key))\n            .thenApply(value -\u003e McpSchema.CallToolResult.builder()\n                    .addTextContent(\"Result: \" + value)\n                    .isError(false)\n                    .build());\n\n\n});\n        }\n```\n\n### Step 7: Package Placement\n\n#### Contributing to This Project\n\nIf you are contributing a handler to this project, place your handler in the appropriate package:\n\n- **Lettuce handlers**: `io.redis.mcp.java.core.handlers.lettuce`\n- **Jedis handlers**: `io.redis.mcp.java.core.handlers.jedis`\n\nHandlers in these packages will be automatically discovered and registered when users call:\n\n```java\nRedisToolsRepository.getSyncToolSpecifications(String redisUrl, int maxConnections)\n```\n\n#### Custom Handler Development\n\nIf you are developing your own handler in a custom package, pass the package name to the `RedisToolsRepository` for\nmanual instantiation:\n\n```java\nRedisToolsRepository.getSyncToolSpecifications(String redisUrl, int maxConnections, List\u003cString\u003e packages)\n```\n\n## Usage\n\n### Basic Setup\n\n```java\n// Create tool specifications\nvar toolSpecs = RedisToolsRepository.getSyncToolSpecifications(\n                \"redis://localhost:6379\",\n                10  // max connections\n        );\n\n// Register with the Java MCP server\nmcpServer.\n\nregisterTools(toolSpecs);\n```\n\n### Custom Package Scanning\n\n```java\nvar customPackages = List.of(\n        \"com.mycompany.redis.handlers\",\n        \"io.redis.mcp.java.core.handlers.lettuce\"\n);\n\nvar toolSpecs = RedisToolsRepository.getSyncToolSpecifications(\n        \"redis://localhost:6379\",\n        10,\n        customPackages\n);\n```\n\n## Spring Boot MCP Server\n\nThe project includes a ready-to-run Spring Boot application that provides a complete MCP server with Redis tool\nintegration.\n\n\u003e **Future Development**: We are planning to develop Spring-specific annotations, annotation processors, and\n\u003e auto-configuration starters to streamline the integration of redis-mcp-java with Spring MCP in a future release. This\n\u003e will provide declarative configuration and automatic setup. For now, manual MCP server configuration is required, but\n\u003e the current approach is straightforward and provides full control over the setup.\n\n### Configuration\n\nConfigure Redis connection settings in `spring/src/main/resources/application.properties`:\n\n```properties\n# Redis MCP Configuration\nredis.mcp.url=redis://localhost:6379\nredis.mcp.pool.size=4\n```\n\n### Running the Application\n\n#### Using Gradle\n\n```bash\n# Run the Spring Boot application\n./gradlew :spring:bootRun\n\n# Or build and run the JAR\n./gradlew :spring:bootJar\njava -jar spring/build/libs/spring-*.jar\n```\n\n#### Configuration Override\n\nYou can override configuration via environment variables or command-line arguments:\n\n```bash\n# Via environment variables\nexport REDIS_MCP_URL=redis://production-redis:6379\nexport REDIS_MCP_POOL_SIZE=10\n./gradlew :spring:bootRun\n\n# Via command line arguments\n./gradlew :spring:bootRun --args=\"--redis.mcp.url=redis://staging:6379 --redis.mcp.pool.size=8\"\n\n# Or with JAR\njava -jar spring/build/libs/spring-*.jar --redis.mcp.url=redis://custom:6379\n```\n\n### MCP Server Endpoints\n\nOnce running, the MCP server provides:\n\n- **Server-Sent Events Endpoint**: `http://localhost:8080/mcp/message`\n- **Available Tools**: Automatically discovered Redis handlers (GET, SET, JSON.GET, JSON.SET)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredis%2Fredis-mcp-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredis%2Fredis-mcp-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredis%2Fredis-mcp-java/lists"}