Germain-D/pulsar-mcp-server

Pulsar MCP Server

A Model Context Protocol (MCP) server for Apache Pulsar that provides tools to interact with Pulsar clusters through MCP-compatible clients.

Features

• Publish Messages: Send messages to Pulsar topics with optional properties
• Consume Messages: Receive messages from topics with configurable subscription settings
• Topic Management: Create, delete, and list topics
• Topic Statistics: Get detailed statistics and metadata about topics
• Connector Management: List, get status, and configuration of Pulsar IO connectors
• Flexible Configuration: Environment-based configuration with sensible defaults

Installation

From Source

1. Clone the repository:

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

2. Install dependencies:

pip install -r requirements.txt

3. Install the package in development mode:

pip install -e .

Using pip (when published)

pip install pulsar-mcp-server

Usage

Command Line

After installation, you can run the server using:

pulsar-mcp-server

The server will start and listen for MCP requests via stdio.

Programmatic Usage

from pulsar_mcp_server import main

# Run the server
main()

Cursor MCP Server Usage

In your ~/.cursor/mcp.json file, add the following:

  "pulsar": {
    "command": "pulsar-mcp-server",
    "env": {
        "PULSAR_SERVICE_URL": "pulsar://localhost:6650",
        "PULSAR_WEB_SERVICE_URL": "http://localhost:8080"
    }
}

Configuration

The server can be configured using environment variables or a .env file:

# Pulsar connection settings
PULSAR_SERVICE_URL=pulsar://localhost:6650
PULSAR_WEB_SERVICE_URL=http://localhost:8080

# Topic and subscription settings
TOPIC_NAME=my-topic
SUBSCRIPTION_NAME=pulsar-mcp-subscription
SUBSCRIPTION_TYPE=Shared
IS_TOPIC_READ_FROM_BEGINNING=false

# Authentication (optional)
PULSAR_TOKEN=your-jwt-token
PULSAR_TLS_TRUST_CERTS_FILE_PATH=/path/to/certs
PULSAR_TLS_ALLOW_INSECURE_CONNECTION=false

Available Tools

pulsar_publish

Publish a message to a Pulsar topic.

Parameters:

• topic (string, required): The Pulsar topic to publish to
• message (string, required): The message content to publish
• properties (object, optional): Message properties as key-value pairs

pulsar_consume

Consume messages from a Pulsar topic.

Parameters:

• topic (string, required): The Pulsar topic to consume from
• subscription_name (string, required): The subscription name
• max_messages (integer, optional): Maximum number of messages to consume (default: 10)

pulsar_create_topic

Create a new Pulsar topic.

Parameters:

• topic (string, required): Name of the topic to create
• partitions (integer, optional): Number of partitions (default: 1)

pulsar_delete_topic

Delete an existing Pulsar topic.

Parameters:

• topic (string, required): Name of the topic to delete

pulsar_list_topics

List all topics in the Pulsar cluster.

Parameters: None

pulsar_topic_stats

Get statistics and metadata about a topic.

Parameters:

• topic (string, required): Name of the topic to get stats for

pulsar_list_connectors

List all connectors of a specified type (source or sink).

Parameters:

• connector_type (string, optional): Type of connectors to list ("source" or "sink", default: "source")

pulsar_connector_status

Get the status of a specific connector.

Parameters:

• connector_name (string, required): Name of the connector to get status for

pulsar_connector_config

Get the configuration of a specific connector.

Parameters:

• connector_name (string, required): Name of the connector to get configuration for

pulsar_all_connectors

Get all connectors organized by type (source and sink).

Parameters: None

Development

Project Structure

pulsar-mcp-server/
├── src/
│   └── pulsar_mcp_server/
│       ├── __init__.py          # Package entry point
│       ├── server.py            # MCP server implementation
│       ├── pulsar_connector.py  # Pulsar client wrapper
│       └── settings.py          # Configuration settings
├── pyproject.toml               # Project configuration
├── requirements.txt             # Dependencies
├── test_server.py              # Test script
└── README.md                   # This file

Testing

Run the test script to verify the server functionality:

python test_server.py

Running with Docker

You can also run Pulsar locally using Docker for testing:

# Start Pulsar standalone
docker run -it -p 6650:6650 -p 8080:8080 apachepulsar/pulsar:latest bin/pulsar standalone

Requirements

• Python 3.12+
• Apache Pulsar cluster (local or remote)
• MCP-compatible client

Dependencies

• mcp>=1.1.0,<2.0: Model Context Protocol library
• pulsar-client>=3.4.0: Apache Pulsar Python client
• pydantic>=2.10.3: Data validation and settings management
• pydantic-settings>=2.6.1: Settings management for Pydantic

License

MIT License

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions, please open an issue on the GitHub repository.