Meshery MCP Server

Meshery MCP Server connects AI assistants to Meshery through the Model Context Protocol (MCP), an open standard for connecting AI applications to external systems. Any MCP-capable client, such as Claude Desktop, Claude Code, or an IDE agent, can then work with Meshery designs through one consistent interface instead of a custom integration per assistant.

It is an official Meshery Extension, written in Go, and runs as a standalone binary or container next to your Meshery deployment.

Project status

[!NOTE] Early development. The project scaffold is in place, but the MCP server itself is not implemented yet: the binary currently loads and validates its configuration, logs a startup line, and exits.

Planned scope

In priority order, the server will support:

1. Creating Meshery designs.
2. Retrieving designs in the format the user asks for (for example JSON or YAML).
3. Snapshotting Meshery designs.
4. Dry-run results for design deployments.
5. Defining and running performance tests, and retrieving their results.

These will be exposed through MCP’s three building blocks:

• Tools: Meshery operations the AI can invoke on the user’s behalf.
• Resources: Meshery data the AI can read as context.
• Prompts: reusable prompt templates for common Meshery workflows.

Architecture

┌──────────────────────────────────────────────────────────────┐
│ MCP client: Claude Desktop, Claude Code, IDE agents, ...     │
│ starts the server as a child process                         │
└──────────────────────────────────────────────────────────────┘
                                │  JSON-RPC over stdio (stdin/stdout)
                                ▼
┌──────────────────────────────────────────────────────────────┐
│ meshery-mcp-server                                           │
│                                                              │
│ cmd/meshery-mcp-server  entrypoint: flags, logger, wiring    │
│ internal/config         settings from env vars and file      │
│                                                              │
│ internal/tools          MCP tools          (planned)         │
│ internal/resources      MCP resources      (planned)         │
│ internal/prompts        MCP prompts        (planned)         │
│ internal/meshery        Meshery API client (planned)         │
│                                                              │
│ logs go to stderr; stdout is reserved for the protocol       │
└──────────────────────────────────────────────────────────────┘
                                │  HTTP(S) + provider token
                                ▼
┌──────────────────────────────────────────────────────────────┐
│ Meshery Server  (MESHERY_SERVER_URL)                         │
└──────────────────────────────────────────────────────────────┘

The MCP client launches the server and talks to it over stdin/stdout, so the server does not listen on any network address. Because stdout carries the protocol, all logs go to stderr.

Only cmd/meshery-mcp-server wires the packages together. internal/config is the only package that reads environment variables or the config file; the other packages receive plain values from main. See docs/config.md for details.

Repository structure

meshery-mcp-server/
├── .github/workflows/          # CI: lint, build and test, Docker image
├── build/                      # Shared Makefile includes
├── cmd/meshery-mcp-server/     # Entrypoint
├── docs/
│   └── config.md               # Configuration reference
├── helpers/
│   └── component_info.json     # Error-code metadata for Meshery's errorutil
├── internal/
│   ├── config/                 # Configuration loading and validation
│   ├── meshery/                # Meshery API client
│   ├── prompts/                # MCP prompts
│   ├── resources/              # MCP resources
│   └── tools/                  # MCP tools
├── .dockerignore
├── .golangci.yml               # Lint configuration
├── config_example.yml          # Example config file
├── Dockerfile                  # Multi-stage build, distroless non-root runtime
├── go.mod / go.sum
└── Makefile                    # Build and development commands

Quick start

Prerequisites

1. Clone and build

git clone https://github.com/meshery-extensions/meshery-mcp-server.git
cd meshery-mcp-server
make build            # writes bin/meshery-mcp-server

2. Configure

The server works with no configuration if Meshery runs at http://localhost:9081. Otherwise, set environment variables:

To use a config file instead:

cp config_example.yml config.local.yaml   # *.local.yaml is gitignored

and pass it with --config config.local.yaml. Environment variables override the file.

docs/config.md is the full reference: precedence rules, token handling, Docker specifics and every error message.

3. Run

make run
make run ARGS="--config config.local.yaml"

Today this prints a startup line to stderr and exits:

time="..." level=info msg="starting meshery-mcp-server version=... commit=... meshery_url=http://localhost:9081 token_configured=false" app=meshery-mcp-server

4. Run in a container

make docker-run

This builds the image and runs it over stdio. Inside a container, localhost refers to the container itself, so make docker-run points the server at http://host.docker.internal:9081 by default. Override it with DOCKER_MESHERY_SERVER_URL. MESHERY_API_TOKEN is forwarded from your shell.

5. Connect an MCP client

[!NOTE] This becomes useful once the MCP server is implemented.

MCP clients start the server themselves. For example, in Claude Desktop’s configuration:

{
  "mcpServers": {
    "meshery": {
      "command": "/path/to/meshery-mcp-server",
      "env": {
        "MESHERY_SERVER_URL": "http://localhost:9081",
        "MESHERY_API_TOKEN": ""
      }
    }
  }
}

Point the client at the binary or at docker run -i ..., never at make: Make prints its commands to stdout, which would corrupt the MCP stream. docs/config.md has the Docker version.

Development

Every pull request runs three CI jobs: golangci-lint, Build and unit tests (tidy check, build, tests with coverage), and Test Docker Image Build (builds the image and starts it). Run make lint and make coverage before opening one.

Errors follow Meshery’s error conventions: each package defines its errors in error.go with "replace_me" codes, which Meshery’s errorutil tool replaces with real ones. To check your errors locally:

go run github.com/meshery/meshkit/cmd/errorutil -d . analyze -i ./helpers -o ./helpers

About Meshery Extensions

Meshery Extensions add capabilities to Meshery beyond its core platform. They live in the meshery-extensions organization, separate from the core meshery organization; the ecosystem expansion post explains why and how that organization is governed.

Related repositories:

• meshery/meshery: Meshery core
• meshery/meshkit: shared Go library used here for logging and errors