Hazelcast MCP

Hazelcast客户端MCP服务器

开源 模型上下文协议（MCP） 服务器，使AI代理能够完全访问您的Hazelcast集群。Claude、Cursor、VS Code Copilot和自定义LangChain代理可以查询、编写和管理 每个主要的Hazelcast数据结构 通过自然语言。

57工具 涵盖了IMap、IQueue、IList、ISet、MultiMap、AtomicLong、ITopic、Ringbuffer、SQL和VectorCollection，以及集群发现、访问控制和三种传输选项。

Docker快速入门

零设置，包括演示数据：

# Linux / macOS
HAZELCAST_MCP_TRANSPORT=sse docker compose up --build

# Windows PowerShell
$env:HAZELCAST_MCP_TRANSPORT="sse"; docker compose up --build

这将启动一个启用Jet的Hazelcast节点，用实时流媒体馈送种子财务演示数据，并在以下位置启动MCP服务器 http://localhost:3000/mcp.

连接克劳德桌面

Claude Desktop使用stdio，因此我们与 mcp-remote （要求 18+).

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "hazelcast": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

重新启动克劳德桌面。单击锤子图标以验证是否显示57个Hazelcast工具。

故障排除：

• 没有锤子图标？ 确保Docker正在运行，MCP服务器健康(docker compose ps).
• JSON解析错误？ 验证时间 Jsonlin.com.常见错误：配置块之间缺少逗号。
• 视窗 HAZELCAST_MCP_TRANSPORT=sse 不承认？ 使用PowerShell $env: 语法如上所示。

特性

工具（57次操作）

群集发现

IMap（14个工具）

Hazelcast核心键值存储的完整CRUD和高级操作。

SQL（4个工具）

IQueue（6个工具）

用于任务处理和工作分配的分布式FIFO队列。

IList（5个工具）

具有基于索引访问的分布式有序列表。

ISet（5个工具）

具有唯一性保证的分布式集合。

MultiMap（7个工具）

每个键支持多个值的映射——非常适合标签、类别和一对多关系。

AtomicLong（5个工具）

通过CP子系统的分布式原子计数器——可线性化，在整个集群中保持一致。

注： AtomicLong需要 CP子系统 在您的Hazelcast集群上启用。如果未配置CP，这些工具会优雅地报告错误。

ITopic（2个工具）

分布式发布/订阅消息。

环形缓冲区（5个工具）

固定容量循环缓冲区——非常适合审计日志、事件流和最近的历史查询。

矢量集合（4个工具）

语义相似性搜索（需要Hazelcast 5.7+/-6.0+和向量模块）。

资源（只读集群上下文）

• hazelcast://cluster/info --群集名称、版本、成员列表
• hazelcast://cluster/health --连接状态和延迟
• hazelcast://structures/list --所有类型和大小的分布式对象

提示（可重用的交互模式）

• cache-lookup --检查缓存命中率/未命中率并给出解释
• data-exploration --发现并采样集群数据
• vector-search --语义相似度搜索工作流程

运输

• 标准 --本地AI客户端的标准MCP传输（Claude Desktop、Cursor）
• 流式HTTP --网络可访问MCP的推荐HTTP传输（协议2025-06-18）
• SSE（传统） --较旧的HTTP服务器发送事件传输（协议2024-11-05）

示例提示

这些提示适用于Claude Desktop（或任何MCP客户端），并展示了全方位的工具。Claude会自动将自然语言翻译成正确的工具调用。

群集发现

"What data structures are in my Hazelcast cluster?"
"Show me everything in the cluster — maps, queues, lists, all of it"

地图和SQL（适用于演示数据）

"Get AAPL from the market-data map"
"Show me all keys in the trades map"
"Find Tesla trades: SELECT * FROM trades WHERE symbol='TSLA'"
"What are the top 5 trades by notional value?"
"How many buy vs sell trades? Group by side."
"Compare risk metrics for all three accounts"

队列

"Create a queue called 'work-items' and add three tasks to it"
"How many items are in the work-items queue?"
"Poll the next item from work-items"
"Peek at the head of the queue without removing it"
"Drain all remaining items"

列表和集合

"Create a list called 'watchlist' with AAPL, GOOGL, TSLA, NVDA"
"What's the third item in the watchlist?"
"Get items 0 through 3 from the watchlist"
"Create a set called 'active-symbols' and add AAPL, MSFT, AAPL — verify AAPL isn't duplicated"
"Is AMZN in the active-symbols set?"

多重映射

"Create a multimap called 'user-roles' — give user 'brian' the roles admin, editor, and viewer"
"What roles does brian have?"
"How many roles does brian have vs user 'guest'?"
"Remove the viewer role from brian"
"List all keys and values in user-roles"

原子计数器

"Create an atomic counter called 'request-count' starting at 0"
"Increment request-count 5 times and show the final value"
"Use compare-and-set: if request-count is 5, set it to 1000"

主题和Ringbuffers

"Publish an alert to the 'notifications' topic: {\"type\": \"warning\", \"message\": \"High CPU usage\"}"
"Add 5 log entries to a ringbuffer called 'audit-log'"
"Read the last 3 entries from audit-log"
"What's the capacity of the audit-log ringbuffer?"

SQL-DDL

"Show all SQL mappings in the cluster"
"Create a SQL mapping for the trades map with varchar keys and json values"
"Now query it: SELECT * FROM trades LIMIT 5"
"Drop the trades mapping"

端到端工作流

"Build me a job processing system: create a 'jobs' queue with 5 tasks, a 'completed' set to
track finished work, and a 'jobs-processed' counter. Then process 2 jobs — poll from the queue,
add to the completed set, and increment the counter each time."

"Set up a market alert system: create a 'price-alerts' multimap where each symbol can have
multiple alert thresholds. Add alerts for AAPL at 150 and 200, TSLA at 250. Then check what
alerts exist for AAPL."

"Audit everything: list all structures in the cluster, check the sizes of each map, show me the
queue depths, and give me a summary of what's in the cluster."

演示数据

Docker快速入门包括一个带有实时流媒体提要的金融交易数据集。

静态种子数据

符号： AAPL、GOOGL、MSFT、AMZN、TSLA、JPM、GS、NVDA、META、NFLX、BAC、INTC

实时数据馈送

加密货币开箱即用。 股票和新闻是可选的：

ALPHA_VANTAGE_API_KEY=your_key NEWS_API_KEY=your_key HAZELCAST_MCP_TRANSPORT=sse docker compose up --build

免费API密钥： 阿尔法优势 （每天需要25次）· 新闻API （每天100个要求）

快速入门（无Docker）

先决条件

• Java 17+
• 正在运行的Hazelcast集群（建议5.5+/5.6）

构建

./mvnw clean package -DskipTests

配置

创建 hazelcast-mcp.yaml:

hazelcast:
  cluster:
    name: "dev"
    members:
      - "127.0.0.1:5701"

mcp:
  server:
    name: "hazelcast-mcp-server"
    version: "1.0.0"
    transport: "stdio"    # or "sse" for Streamable HTTP, "sse-legacy" for legacy SSE
    http:
      port: 3000
      host: "0.0.0.0"

access:
  mode: "all"
  operations:
    sql: true
    write: true
    clear: false

使用Claude Desktop（stdio）运行

{
  "mcpServers": {
    "hazelcast": {
      "command": "java",
      "args": ["-jar", "/path/to/hazelcast-mcp-server-1.0.0-SNAPSHOT.jar"],
      "env": {
        "HAZELCAST_MCP_CLUSTER_NAME": "dev",
        "HAZELCAST_MCP_CLUSTER_MEMBERS": "127.0.0.1:5701"
      }
    }
  }
}

使用Claude Desktop运行（可流式HTTP）

# Start server
HAZELCAST_MCP_TRANSPORT=sse java -jar hazelcast-mcp-server-1.0.0-SNAPSHOT.jar

{
  "mcpServers": {
    "hazelcast": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

使用光标运行

添加 .cursor/mcp.json:

{
  "mcpServers": {
    "hazelcast": {
      "command": "java",
      "args": ["-jar", "/path/to/hazelcast-mcp-server-1.0.0-SNAPSHOT.jar"]
    }
  }
}

Docker+stdio（替代方案）

{
  "mcpServers": {
    "hazelcast": {
      "command": "docker",
      "args": ["exec", "-i", "hazelcast-mcp-server",
               "java", "-Xmx512m", "-cp", "hazelcast-mcp-server.jar",
               "com.hazelcast.mcp.server.HazelcastMcpServer",
               "/app/hazelcast-mcp.yaml"]
    }
  }
}

配置参考

环境变量

访问控制

限制哪些数据结构和操作暴露给AI代理：

access:
  mode: "allowlist"          # "all" (default), "allowlist", or "denylist"
  allowlist:
    maps: ["session-cache", "user-profiles"]
    vectors: ["document-embeddings"]
    queues: ["task-queue"]
    lists: []                # empty = allow all
    sets: []
    multimaps: []
    topics: []
    ringbuffers: []
    atomics: []
  denylist:                  # used when mode is "denylist"
    maps: ["internal-config"]
    queues: ["system-queue"]
  operations:
    sql: true
    write: false             # read-only mode
    clear: false             # destructive ops require explicit enable

建筑

AI Agent (Claude, Cursor, etc.)
    │ MCP Protocol (stdio or Streamable HTTP)
    ▼
Hazelcast Client MCP Server
    ├── MapTools         (14)  — IMap CRUD + atomic ops + predicate queries
    ├── SqlTools          (4)  — SQL DML/DDL with parameterized queries
    ├── QueueTools        (6)  — IQueue offer/poll/drain/clear
    ├── CollectionTools  (10)  — IList + ISet operations
    ├── MultiMapTools     (7)  — Multi-value map operations
    ├── AtomicTools       (5)  — CP Subsystem atomic counters
    ├── TopicTools        (2)  — Pub/sub messaging
    ├── RingbufferTools   (5)  — Circular buffer read/write
    ├── VectorTools       (4)  — Semantic similarity search
    ├── ClusterResources  (3)  — Read-only cluster context
    ├── AccessController       — Per-structure allowlist/denylist + operation gating
    └── Transport Layer        — stdio / Streamable HTTP / legacy SSE (Jetty 12)
            │ Hazelcast Binary Protocol
            ▼
    Hazelcast Cluster (5.5+)

技术栈

• 语言：Java 17+
• MCP-SDK: MCP Java SDK v1.0.0 GA（杰克逊2.x）
• MCP协议：2025-06-18（流式HTTP），2024-11-05（传统SSE）
• Hazelcast客户端：5.6（与5.5+兼容）
• 运输：stdio（本地），通过嵌入式Jetty 12流式传输HTTP/传统SSE
• 构建：Maven通过胖JAR maven-shade-plugin
• 码头工人：多阶段构建(eclipse-temurin:17)，撰写快速入门
• 实时数据：CoinGecko、Alpha Vantage、与Hazelcast Jet合作的NewsAPI
• 经过测试：克劳德桌面+ mcp-remote 0.1.37（Windows和macOS）

已知问题

• Jackson 3.x类路径冲突。 MCP SDK 1.0.0可传递地包括 mcp-json-jackson3 这带来了杰克逊3.x，导致 NoSuchFieldError: POJO 在运行时。本项目不包括 mcp-json-jackson3 在 pom.xml 并使用 mcp-json-jackson2 只有。如果您进行分叉或升级，请保留此排除。
• AtomicLong需要CP子系统。 如果集群上未启用CP，则5个原子工具将返回描述性错误消息，而不是默默失败。

许可证

Apache许可证2.0