The implementation of Model Context Protocol (MCP) server for VictoriaLogs. This provides access to your VictoriaLogs instance and seamless integration with VictoriaLogs APIs and documentation. It can give you a comprehensive interface for logs, observability, and debugging tasks related to your VictoriaLogs instances, enable advanced automation and interaction capabilities for engineers and tools
Add this skill
npx mdskills install VictoriaMetrics-Community/mcp-victorialogsComprehensive MCP server with extensive VictoriaLogs integration, multiple transport modes, and excellent documentation
1# VictoriaLogs MCP Server23[](https://github.com/VictoriaMetrics-Community/mcp-victorialogs/releases)4[](https://archestra.ai/mcp-catalog/victoriametrics-community__mcp-victorialogs)5[](https://smithery.ai/server/@VictoriaMetrics-Community/mcp-victorialogs)67891011The implementation of [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [VictoriaLogs](https://docs.victoriametrics.com/victorialogs/).1213This provides access to your VictoriaLogs instance and seamless integration with [VictoriaLogs APIs](https://docs.victoriametrics.com/victorialogs/querying/#http-api) and [documentation](https://docs.victoriametrics.com/victorialogs/).14It can give you a comprehensive interface for logs, observability, and debugging tasks related to your VictoriaLogs instances, enable advanced automation and interaction capabilities for engineers and tools.1516## Features1718This MCP server allows you to use almost all read-only APIs of VictoriaLogs, i.e. all functions available in [Web UI](https://docs.victoriametrics.com/victorialogs/querying/#web-ui):1920- Querying logs and exploring logs data21- Showing parameters of your VictoriaLogs instance22- Listing available streams, fields, field values23- Query statistics for the logs as metrics2425In addition, the MCP server contains embedded up-to-date documentation and is able to search it without online access.2627More details about the exact available tools and prompts can be found in the [Usage](#usage) section.2829You can combine functionality of tools, docs search in your prompts and invent great usage scenarios for your VictoriaLogs instance.30And please note the fact that the quality of the MCP Server and its responses depends very much on the capabilities of your client and the quality of the model you are using.3132You can also combine the MCP server with other observability or doc search related MCP Servers and get even more powerful results.3334## Try without installation3536There is a publicly available instance of the VictoriaMetrics MCP Server that you can use to test the features without installing it:3738```39https://play-vmlogs-mcp.victoriametrics.com/mcp40```4142**Attention!** This URL is not supposed to be opened in a browser, it is intended to be used in MCP clients.4344It's available in [Streamable HTTP Mode](#modes) mode and configured to work with [Public VictoriaLogs Playground](https://play-vmlogs.victoriametrics.com).4546Here is example of configuration for [Claude Desktop](https://claude.ai/download):47484950## Requirements5152- [VictoriaLogs](https://docs.victoriametrics.com/victorialogs/) instance: ([single-node](https://docs.victoriametrics.com/victorialogs/) or [cluster](https://docs.victoriametrics.com/victorialogs/cluster/))53- Go 1.24 or higher (if you want to build from source)5455## Installation5657### Go5859```bash60go install github.com/VictoriaMetrics-Community/mcp-victorialogs/cmd/mcp-victorialogs@latest61```6263### Binaries6465Just download the latest release from [Releases](https://github.com/VictoriaMetrics-Community/mcp-victorialogs/releases) page and put it to your PATH.6667Example for Linux x86_64 (note that other architectures and platforms are also available):6869```bash70latest=$(curl -s https://api.github.com/repos/VictoriaMetrics-Community/mcp-victorialogs/releases/latest | grep 'tag_name' | cut -d\" -f4)71wget https://github.com/VictoriaMetrics-Community/mcp-victorialogs/releases/download/$latest/mcp-victorialogs_Linux_x86_64.tar.gz72tar axvf mcp-victorialogs_Linux_x86_64.tar.gz73```7475### Docker7677You can run VictoriaLogs MCP Server using Docker.7879This is the easiest way to get started without needing to install Go or build from source.8081```bash82docker run -d --name mcp-victorialogs \83 -e VL_INSTANCE_ENTRYPOINT=https://play-vmlogs.victoriametrics.com \84 -e MCP_SERVER_MODE=http \85 -e MCP_LISTEN_ADDR=:8081 \86 -p 8081:8081 \87 ghcr.io/victoriametrics-community/mcp-victorialogs88```8990You should replace environment variables with your own parameters.9192Note that the `MCP_SERVER_MODE=http` flag is used to enable Streamable HTTP mode.93More details about server modes can be found in the [Configuration](#configuration) section.9495See available docker images in [github registry](https://github.com/orgs/VictoriaMetrics-Community/packages/container/package/mcp-victorialogs).9697Also see [Using Docker instead of binary](#using-docker-instead-of-binary) section for more details about using Docker with MCP server with clients in stdio mode.9899100### Source Code101102For building binary from source code you can use the following approach:103104- Clone repo:105106 ```bash107 git clone https://github.com/VictoriaMetrics-Community/mcp-victorialogs.git108 cd mcp-victorialogs109 ```110- Build binary from cloned source code:111112 ```bash113 make build114 # after that you can find binary mcp-victorialogs and copy this file to your PATH or run inplace115 ```116- Build image from cloned source code:117118 ```bash119 docker build -t mcp-victorialogs .120 # after that you can use docker image mcp-victorialogs for running or pushing121 ```122123### Smithery124125To install VictoriaLogs MCP Server for your client automatically via [Smithery](https://smithery.ai/server/@VictoriaMetrics-Community/mcp-victorialogs), yo can use the following commands:126127```bash128# Get the list of supported MCP clients129npx -y @smithery/cli list clients130#Available clients:131# claude132# cline133# windsurf134# roocode135# witsy136# enconvo137# cursor138# vscode139# vscode-insiders140# boltai141# amazon-bedrock142143# Install VictoriaLogs MCP server for your client144npx -y @smithery/cli install @VictoriaMetrics-Community/mcp-victorialogs --client <YOUR-CLIENT-NAME>145# and follow the instructions146```147148## Configuration149150MCP Server for VictoriaLogs is configured via environment variables:151152| Variable | Description | Required | Default | Allowed values |153|----------------------------|---------------------------------------------------------|----------|------------------|------------------------|154| `VL_INSTANCE_ENTRYPOINT` | URL to VictoriaLogs instance | Yes | - | - |155| `VL_INSTANCE_BEARER_TOKEN` | Authentication token for VictoriaLogs API | No | - | - |156| `VL_INSTANCE_HEADERS` | Custom HTTP headers to send with requests (comma-separated key=value pairs) | No | - | - |157| `VL_DEFAULT_TENANT_ID` | Default tenant ID used when tenant is not specified in requests (format: `AccountID:ProjectID` or `AccountID`) | No | `0:0` | - |158| `MCP_SERVER_MODE` | Server operation mode. See [Modes](#modes) for details. | No | `stdio` | `stdio`, `sse`, `http` |159| `MCP_LISTEN_ADDR` | Address for SSE or HTTP server to listen on | No | `localhost:8081` | - |160| `MCP_DISABLED_TOOLS` | Comma-separated list of tools to disable | No | - | - |161| `MCP_HEARTBEAT_INTERVAL` | Defines the heartbeat interval for the streamable-http protocol. <br /> It means the MCP server will send a heartbeat to the client through the GET connection, <br /> to keep the connection alive from being closed by the network infrastructure (e.g. gateways) | No | `30s` | - |162| `MCP_LOG_FORMAT` | Log output format | No | `text` | `text`, `json` |163| `MCP_LOG_LEVEL` | Minimum log level | No | `info` | `debug`, `info`, `warn`, `error` |164165### Modes166167MCP Server supports the following modes of operation (transports):168169- `stdio` - Standard input/output mode, where the server reads commands from standard input and writes responses to standard output. This is the default mode and is suitable for local servers.170- `sse` - Server-Sent Events. Server will expose the `/sse` and `/message` endpoints for SSE connections.171- `http` - Streamable HTTP. Server will expose the `/mcp` endpoint for HTTP connections.172173More info about traqnsports you can find in MCP docs:174175- [Core concepts -> Transports](https://modelcontextprotocol.io/docs/concepts/transports)176- [Specifications -> Transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports)177178### Сonfiguration examples179180```bash181# For a public playground182export VL_INSTANCE_ENTRYPOINT="https://play-vmlogs.victoriametrics.com"183184# Custom headers for authentication (e.g., behind a reverse proxy)185# Expected syntax is key=value separated by commas186export VL_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"187188# Server mode189export MCP_SERVER_MODE="sse"190export MCP_SSE_ADDR="0.0.0.0:8081"191export MCP_DISABLED_TOOLS="hits,facets"192```193194## Endpoints195196In SSE and HTTP modes the MCP server provides the following endpoints:197198| Endpoint | Description |199|---------------------|--------------------------------------------------------------------------------------------------|200| `/sse` + `/message` | Endpoints for messages in SSE mode (for MCP clients that support SSE) |201| `/mcp` | HTTP endpoint for streaming messages in HTTP mode (for MCP clients that support Streamable HTTP) |202| `/metrics` | Metrics in Prometheus format for monitoring the MCP server |203| `/health/liveness` | Liveness check endpoint to ensure the server is running |204| `/health/readiness` | Readiness check endpoint to ensure the server is ready to accept requests |205206## Setup in clients207208### Cursor209210Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` and paste the following configuration into your Cursor `~/.cursor/mcp.json` file:211212```json213{214 "mcpServers": {215 "victorialogs": {216 "command": "/path/to/mcp-victorialogs",217 "env": {218 "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",219 "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",220 "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"221 }222 }223 }224}225```226227See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.228229### Claude Desktop230231Add this to your Claude Desktop `claude_desktop_config.json` file (you can find it if open `Settings` -> `Developer` -> `Edit config`):232233```json234{235 "mcpServers": {236 "victorialogs": {237 "command": "/path/to/mcp-victorialogs",238 "env": {239 "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",240 "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",241 "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"242 }243 }244 }245}246```247248See [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info.249250### Claude Code251252Run the command:253254```sh255claude mcp add victorialogs -- /path/to/mcp-victorialogs \256 -e VL_INSTANCE_ENTRYPOINT=<YOUR_VL_INSTANCE> \257 -e VL_INSTANCE_BEARER_TOKEN=<YOUR_VL_BEARER_TOKEN> \258 -e VL_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"259```260261See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp) for more info.262263### Visual Studio Code264265Add this to your VS Code MCP config file:266267```json268{269 "servers": {270 "victorialogs": {271 "type": "stdio",272 "command": "/path/to/mcp-victorialogs",273 "env": {274 "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",275 "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",276 "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"277 }278 }279 }280}281```282283See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.284285### Zed286287Add the following to your Zed config file:288289```json290 "context_servers": {291 "victorialogs": {292 "command": {293 "path": "/path/to/mcp-victorialogs",294 "args": [],295 "env": {296 "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",297 "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",298 "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"299 }300 },301 "settings": {}302 }303 }304}305```306307See [Zed MCP docs](https://zed.dev/docs/ai/mcp) for more info.308309### JetBrains IDEs310311- Open `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)`.312- Click `Add (+)`313- Select `As JSON`314- Put the following to the input field:315316```json317{318 "mcpServers": {319 "victorialogs": {320 "command": "/path/to/mcp-victorialogs",321 "env": {322 "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",323 "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",324 "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"325 }326 }327 }328}329```330331### Windsurf332333Add the following to your Windsurf MCP config file.334335```json336{337 "mcpServers": {338 "victorialogs": {339 "command": "/path/to/mcp-victorialogs",340 "env": {341 "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",342 "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",343 "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"344 }345 }346 }347}348```349350See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) for more info.351352### Using Docker instead of binary353354You can run VictoriaLogs MCP Server using Docker instead of local binary.355356You should replace run command in configuration examples above in the following way:357358```359{360 "mcpServers": {361 "victorialogs": {362 "command": "docker",363 "args": [364 "run",365 "-i", "--rm",366 "-e", "VL_INSTANCE_ENTRYPOINT",367 "-e", "VL_INSTANCE_BEARER_TOKEN",368 "-e", "VL_INSTANCE_HEADERS",369 "ghcr.io/victoriametrics-community/mcp-victorialogs",370 ],371 "env": {372 "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",373 "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",374 "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"375 }376 }377 }378}379```380381## Usage382383After [installing](#installation) and [configuring](#setup-in-clients) the MCP server, you can start using it with your favorite MCP client.384385You can start dialog with AI assistant from the phrase:386387```388Use MCP VictoriaLogs in the following answers389```390391But it's not required, you can just start asking questions and the assistant will automatically use the tools and documentation to provide you with the best answers.392393### Toolset394395MCP VictoriaLogs provides numerous tools for interacting with your VictoriaLogs instance.396397Here's a list of available tools:398399| Tool | Description |400|----------------------|-------------------------------------------------------|401| `documentation` | Search in embedded VictoriaLogs documentation |402| `facets` | Most frequent values per each log field |403| `field_names` | List of field names for the query |404| `field_values` | List of field values for the query |405| `flags` | View non-default flags of the VictoriaLogs instance |406| `hits` | The number of matching log entries grouped by buckets |407| `query` | Execute LogsQL queries |408| `stats_query` | Querying log stats for the given time |409| `stats_query_range` | Querying log stats on the given time range |410| `stream_field_names` | List of stream fields for the query |411| `stream_field_values` | List of stream field values for the query |412| `stream_ids` | List of stream IDs for the query |413| `streams` | List of streams for the query |414415### Prompts416417The server includes pre-defined prompts for common tasks.418419These are just examples at the moment, the prompt library will be added to in the future:420421| Prompt | Description |422|--------|-------------------------------------------------------|423| `documentation` | Search VictoriaLogs documentation for specific topics |424425## Roadmap426427- [ ] Support "Explain query" tool428- [ ] Support optional integration with [VictoriaMetrics Cloud](https://victoriametrics.com/products/cloud/)429- [ ] Add some extra knowledge to server in addition to current documentation tool:430 - [x] [VictoriaMetrics blog](https://victoriametrics.com/blog/) posts431 - [ ] Github issues432 - [ ] Public slack chat history433 - [ ] CRD schemas434- [ ] Implement multitenant version of MCP (that will support several deployments)435- [ ] Add flags/configs validation tool436- [x] Enabling/disabling tools via configuration437438## Disclaimer439440AI services and agents along with MCP servers like this cannot guarantee the accuracy, completeness and reliability of results.441You should double check the results obtained with AI.442443The quality of the MCP Server and its responses depends very much on the capabilities of your client and the quality of the model you are using.444445## Contributing446447Contributions to the MCP VictoriaLogs project are welcome!448449Please feel free to submit issues, feature requests, or pull requests.450
Full transparency — inspect the skill content before installing.