{"id":48524623,"url":"https://github.com/spectrocloud/palette-mcp-server","last_synced_at":"2026-04-28T18:04:53.196Z","repository":{"id":349775843,"uuid":"1010683080","full_name":"spectrocloud/palette-mcp-server","owner":"spectrocloud","description":"An MCP server for Palette","archived":false,"fork":false,"pushed_at":"2026-04-07T14:29:30.000Z","size":833,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T15:15:25.442Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://spectrocloud.com","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spectrocloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-06-29T15:37:52.000Z","updated_at":"2026-04-07T14:30:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/spectrocloud/palette-mcp-server","commit_stats":null,"previous_names":["spectrocloud/palette-mcp-server"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/spectrocloud/palette-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spectrocloud%2Fpalette-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spectrocloud%2Fpalette-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spectrocloud%2Fpalette-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spectrocloud%2Fpalette-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spectrocloud","download_url":"https://codeload.github.com/spectrocloud/palette-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spectrocloud%2Fpalette-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31530647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-07T22:01:02.237Z","updated_at":"2026-04-28T18:04:53.189Z","avatar_url":"https://github.com/spectrocloud.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Palette MCP Server\n\nThe Palette MCP server is a tool for interacting with Palette through the Model Context Protocol (MCP). You can use it to expose function calls to your Large Language Model (LLM) to interact with Palette.\n\n\u003e [!WARNING]\n\u003e This is an experimental project and subject to breaking changes.\n\nThe Palette MCP is a local-first MCP server. The MCP server is hosted in a container that is deployed on your machine. API calls to Palette are sourced from your local machine and target the configured Palette instance.\n\n![Architecture diagram showing the Palette MCP deployed locally and making API calls to Palette](./public/images/arch_diagram.png)\n\n## Tools\n\nThe Palette MCP server provides several tools for interacting with Palette. Several of the function calls expect an action parameter to be provided. The action parameter is used to determine the action to perform. For example, the `gather_or_delete_clusters` tool expects an action parameter of `list`, `get`, or `delete`. If an action contains a dangerous method, the `ALLOW_DANGEROUS_ACTIONS` environment variable must be set to `1` to enable the dangerous method. Otherwise, the dangerous method will be rejected. Check out the [Usage](#usage) section to learn more about how to use the tools. Some tools require explicit enablement before they can be used. Refer to the [Dangerous Actions](#dangerous-actions) section for more information.\n\n| Tool                               | Description                                                                                                                                               | Dangerous Method Included? | Dangerous Method? |\n| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------- |\n| `gather_or_delete_clusters`        | Gather information about clusters or delete a cluster in Palette.                                                                                         | Yes                        | Delete            |\n| `gather_or_delete_clusterprofiles` | Gather information about cluster profiles or delete a cluster profile in Palette.                                                                         | Yes                        | Delete            |\n| `getKubeconfig`                    | Download the kubeconfig or admin kubeconfig for a cluster.                                                                                                | No                         | None              |\n| `search_and_manage_resource_tags`  | Search and manage tag lifecycle operations across the following Palette resources: clusters, cluster profiles, cluster templates, edge hosts, and policy. | Yes                        | Delete            |\n| `search_gather_packs`              | Search for packs by display name or retrieve a specific pack's details by using its ID.                                                                   | No                         | None              |\n\nThe list above will continue to grow as we add more tools to the Palette MCP server.\n\n## Get Started\n\nTo get started with the Palette MCP server, you can use the container image we provide. Review the following steps to get started.\n\n### Prerequisites\n\nThe following items are required to use the Palette MCP server:\n\n- A Palette account.\n- A Palette API key. Check out the [Create API Key](https://docs.spectrocloud.com/user-management/authentication/api-key/create-api-key/) guide for additional guidance.\n- [Docker](https://docs.docker.com/get-docker/) or [Podman](https://podman.io/getting-started/installation) installed on your machine.\n- Network access to the Palette API from your machine.\n- A pre-existing folder to store kubeconfig file retrieved from Palette. This is optional but improves the experience when retrieving Kubeconfig files.\n\n### Setup\n\nStart by creating a `.env-mcp` file in your home directory under the `.palette` folder. If this folder does not exist, create it.\n\n```bash\nmkdir -p ~/.palette\ntouch ~/.palette/.env-mcp\n```\n\nThe `.env-mcp` file should contain the following variables.\n\n```bash\nSPECTROCLOUD_DEFAULT_PROJECT_ID=your-project-id\nSPECTROCLOUD_APIKEY=your-api-key\nSPECTROCLOUD_HOST=api.spectrocloud.com\nALLOW_DANGEROUS_ACTIONS=0\n```\n\nNext, create a folder to store the kubeconfig file on the host machine. This is optional but improves the experience when retrieving Kubeconfig files. The configuations below assumes the host machine folder is `/home/demouser/kubeconfig` but you can use any folder you prefer. In the following command replace the `/home/demouser/kubeconfig` with the path to your kubeconfig folder.\n\n```bash\nmkdir -p /home/REPLACEME/kubeconfig\n```\n\nNext, use the Palette MCP server, add the following MCP configuration to your application. If you don't want to use Docker, swap out the `docker` command for `podman` in the `command` field. Update the file paths to match your environment. Specify full paths to the kubeconfig folder and the `.env-mcp` file. Be aware that ENV variables such as `$HOME` will not be interpolated in most tools.\n\n\u003e [!WARNING]\n\u003e Ensure you use full path specifications for the kubeconfig folder and the `.env-mcp` file. Do not use relative paths, or `~`, `$HOME`, or other environment variables. Docker requires full paths to be specified for the `--mount` flag. And most tools do not support environment variable interpolation for MCP configurations.\n\n```json\n  \"mcpServers\": {\n    \"palette\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"--pull\",\n        \"always\",\n        \"--mount\",\n        \"type=bind,source=/FILE_PATH_REPLACE_ME/kubeconfig,target=/tmp/kubeconfig\",\n        \"--env-file\",\n        \"/FILE_PATH_REPLACE_ME/.env-mcp\",\n        \"public.ecr.aws/palette-ai/palette-mcp-server:latest\"\n      ]\n    }\n  }\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e💾 Without Env File\u003c/summary\u003e\u003cbr\u003e\n\nIf you don't want to use the `.env` file, you can add the environment variables directly to the MCP configuration.\nHowever, this is not recommended as it may create a scecario where this could get committed to a repository.\n\n```json\n{\n  \"mcpServers\": {\n    \"palette\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--mount\",\n        \"type=bind,source=/FILE_PATH_REPLACE_ME/kubeconfig,target=/tmp/kubeconfig\",\n        \"--rm\",\n        \"-e\",\n        \"SPECTROCLOUD_HOST=api.spectrocloud.com\",\n        \"-e\",\n        \"SPECTROCLOUD_APIKEY=your-api-key\",\n        \"-e\",\n        \"SPECTROCLOUD_DEFAULT_PROJECT_ID=your-project-id\",\n        \"-e\",\n        \"ALLOW_DANGEROUS_ACTIONS=0\",\n        \"public.ecr.aws/palette-ai/palette-mcp-server:latest\"\n      ]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### Validate\n\nOpen up the application you configured to use the Palette MCP server. Issue the following command to ensure the container is active:\n\n```shell\ndocker ps | grep palette-ai/palette-mcp-server\n```\n\nFor example, if you are using Cursor, an output similar to the following should be displayed:\n\n```shell\nde70907c4b6f   public.ecr.aws/palette-ai/palette-mcp-server:latest   \"uv run python src/s…\"   2 minutes ago   Up 2 minutes             palette-mcp-cursor\n```\n\nNext, issue a prompt that uses the Palette MCP server tools. For example, you can issue the following command:\n\n```shell\nCan you use help me identify how many active clusters I have in Palette?\n```\n\nSome applications may require your approval to use the Palette MCP server tools.\n\n## Usage\n\nThere are various ways to use the Palette MCP server tools. The primary way to use the tools is to enable integration with a Large Language Model (LLM) to access the tools. You can enable integration with a LLM by adding the Palette MCP server to the MCP configuration of your application.\n\n### Scope\n\nIf you specified a `SPECTROCLOUD_DEFAULT_PROJECT_ID` in the `.env-mcp` file, the Palette MCP server will always default to using the provided project ID. If you do not provide a project ID, then the tool call requires you to provide a project ID. You can also provide a different project ID as a parameter to the tool call. Or in other words, if working through an LLM, in the prompt you can specify a different project ID to use.\n\n### API Key\n\nSame behavior as `SPECTROCLOUD_DEFAULT_PROJECT_ID` applies to the API key. If you specified a `SPECTROCLOUD_APIKEY` in the `.env-mcp` file, the Palette MCP server will always default to using the provided API key. If you do not provide an API key, then the tool call requires you to provide an API key. You can also provide a different API key as a parameter to the tool call. This allows you to target different organizations by specifying a different API key.\n\n### Dangerous Actions\n\nTo prevent accidental use of dangerous actions, the Palette MCP server requires you to set the `ALLOW_DANGEROUS_ACTIONS` environment variable to `1`. This is a precautionary measure to prevent accidental use of dangerous actions. Review the [Tools](#tools) section to understand which tools are dangerous and require approval.\n\n### Accessing Kubeconfig Files\n\nThe Palette MCP server provides tools to access kubeconfig files for clusters. You can access the kubeconfig files by mounting a local folder to the container with the `--mount` flag in the MCP configuration. In the container, all kubeconfig files are stored in the `/tmp/kubeconfig` folder. If you use the `getKubeconfig` tool (with `admin_config=True` for admin kubeconfig), the kubeconfig file will be stored in the `/tmp/kubeconfig` folder. The filename will have the cluster's UID as the name, for example, `68669fcfee517a7f9a91a9e5.kubeconfig`. Admin kubeconfig files have the suffix `.admin` in the filename, for example, `68669fcfee517a7f9a91a9e5.admin.kubeconfig`.\n\n\u003e [!WARNING]\n\u003e The folder you use to mount to the container will be wiped when the container is stopped and started again. The Palette MCP server will automatically remove the kubeconfig files from its /tmp/kubeconfig folder.\n\nKubeconfig files are written with restricted permissions `0o600`. On **macOS and Windows**, Docker Desktop and Podman remap container UIDs to your host user automatically, so files are accessible without extra steps. On **Linux with rootful Docker or Podman**, files are owned by `root` and your host user may not be able to read the kubeconfig files. You can fix this by issuing the following command:\n\n```bash\n sudo chown $(id -u):$(id -g) /your/kubeconfig/path/to/kubeconfig/\u003ccluster-uid\u003e.kubeconfig\n```\n\nYou can also avoid this entirely by starting the container with `--user $(id -u):$(id -g)`.\n\nOnce you have the kubeconfig file locally, assuming your application with an LLM has access to your local filesystem and a shell environment, you can have the application use the kubeconfig file to access the cluster. For example, if you are using Cursor, you can ask it to use the kubeconfig file to with the `kubectl` command to access the cluster.\n\nWe recommend you provide guidance to LLMs on how to properly use the kubeconfig file to access the cluster. Check out the [example.agents.md](./skills/example.agents.md) file for an example of how to provide guidance to LLMs on how to properly use the kubeconfig file to access the cluster. This assumes you provided a folder to store the kubeconfig files on the host machine using the `--mount` flag in the MCP configuration.\n\n```\n\"--mount\",\n\"type=bind,source=/FILE_PATH_REPLACE_ME/kubeconfig,target=/tmp/kubeconfig\",\n```\n\nIf you use the example agents.md, make sure to replace the file path with the path to your kubeconfig folder.\n\n### Removing a Cluster\n\nTo remove a cluster from Palette, you can use the `gather_or_delete_clusters` tool with `action=\"delete\"`. This tool will delete the cluster from Palette. This tool requires the `ALLOW_DANGEROUS_ACTIONS` environment variable to be set to `1`. The tool call supports a `force_delete` parameter to force the deletion of the cluster. However, keep in mind that force delete can only work if the cluster is in the deletion state. A delete request must be initiated without the force delete flag prior to using force delete.\n\n## Development\n\nStart by creating a `.env` file in the root of the project. This file should contain the following variables:\n\n```bash\nSPECTROCLOUD_DEFAULT_PROJECT_ID=your-project-id\nSPECTROCLOUD_APIKEY=your-api-key\nSPECTROCLOUD_HOST=api.spectrocloud.com\nPHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces\nALLOW_DANGEROUS_ACTIONS=0\n```\n\nNext, issue the command `uv sync --frozen` to install the required Python dependencies.\n\nIf you are using a self-hosted Palette instance, you will need to set the `SPECTROCLOUD_HOST` variable to the URL of your Palette instance.\n\nTo start the local development server, issue the following command in the root of the project:\n\n```bash\ntask start-debug\n```\n\nThis will start the a container for the Phoenix collector and the Palette MCP server. Use the Phoenix AI to review traces to help debug issues and verify expected behavior. Phoenix AI will be available at [http://localhost:6006](http://localhost:6006).\n\nIf you are using a container runtime, the Phoenix collector endpoint will be rewritten to use `host.docker.internal` to ensure the Phoenix collector is accessible from the container. You can also set the `PHOENIX_COLLECTOR_ENDPOINT` environment variable to the Phoenix collector endpoint to use a different endpoint.\n\n```bash\nPHOENIX_COLLECTOR_ENDPOINT=http://host.docker.internal:6006/v1/traces\n```\n\nTo stop the development server, press `Ctrl+C` in the terminal where the server is active. The server will gracefully shutdown and clean up any temporary files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspectrocloud%2Fpalette-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspectrocloud%2Fpalette-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspectrocloud%2Fpalette-mcp-server/lists"}