pulsar

Pulsar MCP Server provides a Java-based implementation that exposes administrative tools for Apache Pulsar alongside client capabilities for producing and consuming messages. The server is designed to run within a containerized environment or as a standalone Java application, wired via Spring Boot and the MCP Server Boot Starter. Use the admin tools to manage tenants, namespaces, topics, brokers, clusters, and functions, and switch to write mode to enable write operations. The client tools allow you to produce messages with properties and keys, and to consume messages using various subscription types. Configure the desired security profile (read-only by default, write-enabled with the appropriate Spring profile) to guard against unintended modifications. Feature flags can be used to enable or disable specific tool groups via configuration, giving you fine-grained control over the capabilities exposed by the server.

Prerequisites:

• Java 17+ (for running the Java-based Pulsar MCP Server)
• Maven 3.6+ (if you choose to build from source)
• Apache Pulsar cluster reachable from the server

Option A: Build from source

1. Clone the repository: git clone https://github.com/denovo1998-pulsar-mcp-server.git cd pulsar-mcp-server

2. Build the project (no tests): mvn clean package -DskipTests

3. Run the built jar (example): java -jar target/pulsar-mcp-server-<version>.jar

Option B: Run via Docker (recommended for quick start)

1. Pull and run the Docker image: docker run -i denovo1998/pulsar-mcp-server:latest

2. If needed, set environment variables for configuration, for example:

   • SPRING_PROFILES_ACTIVE=read (default) or write
   • SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, SPRING_DATASOURCE_PASSWORD

Notes:

• Ensure your Apache Pulsar cluster is accessible from the server process.
• If you use Docker, you may need to expose and map ports as required by your Pulsar setup.
• The read-only mode is the default; switch to write mode by configuring SPRING_PROFILES_ACTIVE=write.

Tips and troubleshooting:

• When in write mode, ensure proper authorization and network access to the Pulsar cluster to avoid permission errors.
• If you customize feature flags, verify that the configuration source is loaded at startup (e.g., application.properties or YAML) and that the flags are valid.
• For Docker deployment, consider using a multi-stage build to minimize image size and ensure the correct Java version is included.
• Common issues may include connectivity problems to Pulsar, incorrect datasource configuration, or missing environment variables. Check logs for hints related to Spring Boot startup and Pulsar client initialization.
• If you need to enable additional tool groups, adjust the configuration to turn on the corresponding feature flags as described in the documentation.