Installation
There are several ways of installing the Perses MCP Server:
Whatever the method you choose, the MCP server needs a running Perses instance and a configuration telling it how to reach Perses.
Precompiled binaries#
Download the precompiled binaries from the GitHub releases page. It is recommended to use the latest release available.
Archives are available for Linux, macOS and Windows, on the x86_64, arm64 and i386 architectures (i386 is not
available for macOS). Each archive contains the binary perses-mcp-server.
For example, on macOS with an Apple silicon processor:
curl -LO "https://github.com/perses/mcp-server/releases/latest/download/perses-mcp-server_Darwin_arm64.tar.gz"
tar -xzf perses-mcp-server_Darwin_arm64.tar.gzThen move the binary to a stable location (for example /usr/local/bin) and note its absolute path: you need it to
configure your LLM host.
Container images#
Container images are available on Docker Hub and on
Quay, for the amd64 and arm64 platforms.
Streamable HTTP mode#
To run the MCP server as an HTTP service, set the transport to http and publish the port it listens on (8000 by
default):
docker run --name perses-mcp-server -d -p 127.0.0.1:8000:8000 \
-e PERMCP_TRANSPORT=http \
-e PERMCP_PERSES_SERVER_URL=https://perses.example.com \
-e PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN=<LOGIN> \
-e PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD=<PASSWORD> \
persesdev/mcp-serverThe MCP endpoint is then available at http://localhost:8000/mcp.
The MCP server is configured here with environment variables. You can also
mount a configuration file and pass it with the flag --config:
docker run --name perses-mcp-server -d -p 127.0.0.1:8000:8000 \
-v "$(pwd)/config.yaml:/etc/perses-mcp-server/config.yaml:ro" \
persesdev/mcp-server --config=/etc/perses-mcp-server/config.yamlBefore exposing the MCP server beyond your machine, read the security considerations.
stdio mode#
The container image can also be started by the LLM host in stdio mode. In this case, the option -i is required to keep
the standard input open:
docker run -i --rm \
-e PERMCP_PERSES_SERVER_URL=https://perses.example.com \
-e PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN=<LOGIN> \
-e PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD=<PASSWORD> \
persesdev/mcp-serverSee MCP clients to use this command in your LLM host.
Tags#
We are publishing a set of tags to match different requirements:
- There are two types of image:
distrolessanddistroless-debug. The first one is meant to be used in production as it doesn't contain anything except the MCP server binary. The second one contains a shell and should be used to debug any issue you might encounter with your container. - Each release is available with the full version (
v0.2.0) or only the minor version (v0.2), with or without the distribution suffix (v0.2.0-distroless,v0.2.0-distroless-debug). Without suffix, the image is thedistrolessone, and the suffix-debugis an alias for-distroless-debug. - The tag
latestis an alias for thedistrolessdistribution of the latest release. - The tag
latest-debugis an alias for thedistroless-debugdistribution of the latest release.
Examples:
docker pull persesdev/mcp-server:v0.2.0
docker pull persesdev/mcp-server:v0.2-debug
docker pull quay.io/persesdev/mcp-server:v0.2.0-distrolessBuilding from source#
To build the MCP server from source, you need Go in the version defined in the
go.mod file of the repository.
Start by cloning the repository:
git clone https://github.com/perses/mcp-server.git
cd mcp-serverThen build the MCP server with:
make buildThe binary is created in the folder bin: bin/perses-mcp-server.

