{"id":50565231,"url":"https://github.com/hashicorp/consul-mcp-server","last_synced_at":"2026-06-04T14:00:47.905Z","repository":{"id":362040375,"uuid":"1052850719","full_name":"hashicorp/consul-mcp-server","owner":"hashicorp","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-02T09:18:47.000Z","size":326,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T11:14:20.830Z","etag":null,"topics":["doormat-managed"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hashicorp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":null,"dco":null,"cla":null}},"created_at":"2025-09-08T16:28:01.000Z","updated_at":"2026-06-02T09:18:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hashicorp/consul-mcp-server","commit_stats":null,"previous_names":["hashicorp/consul-mcp-server"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/hashicorp/consul-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fconsul-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fconsul-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fconsul-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fconsul-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hashicorp","download_url":"https://codeload.github.com/hashicorp/consul-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fconsul-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33907694,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["doormat-managed"],"created_at":"2026-06-04T14:00:46.816Z","updated_at":"2026-06-04T14:00:47.893Z","avatar_url":"https://github.com/hashicorp.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"public/images/consul-fill-color-24.svg\" width=\"30\" align=\"left\" style=\"margin-right: 12px; margin-top: 5px\"/\u003e Consul MCP Server\n\nThe Consul MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)\nserver that provides seamless integration with HashiCorp Consul APIs, enabling advanced\nautomation and interaction capabilities for service discovery, configuration management, and service mesh operations.\n\n## Features\n\n- **Dual Transport Support**: Both Stdio and StreamableHTTP transports\n- **Service Discovery**: Query and manage services, nodes, and health checks in the Consul catalog\n- **Key-Value Store**: Access and manage Consul's distributed key-value store\n- **Service Mesh**: Interact with Consul Connect for service mesh functionality including intentions and certificates\n- **ACL Management**: Manage Access Control Lists including tokens, policies, roles, and auth methods\n- **Agent Operations**: Monitor and configure Consul agents, including health checks and services\n- **Cluster Operations**: Access operator tools for cluster management, autopilot, and Raft operations\n- **Container Ready**: Docker support for easy deployment\n\n\u003e **Caution:** The outputs and recommendations provided by the MCP server are generated dynamically and may vary based on the query, model, and the connected MCP server. Users should **thoroughly review all outputs/recommendations** to ensure they align with their organization's **security best practices**, **compliance requirements**, and **Consul deployment policies** before implementation.\n\n\u003e **Security Note:** When using the StreamableHTTP transport in production, always configure the `MCP_ALLOWED_ORIGINS` environment variable to restrict access to trusted origins only. This helps prevent DNS rebinding attacks and other cross-origin vulnerabilities.\n\n## Prerequisites\n\n1. A running Consul cluster or agent that the MCP server can connect to\n2. For containerized deployment, [Docker](https://www.docker.com/) installed and running\n3. Appropriate Consul ACL tokens if ACL is enabled in your Consul cluster\n\n## Transport Support\n\nThe Consul MCP Server supports multiple transport protocols:\n\n### 1. Stdio Transport (Default)\nStandard input/output communication using JSON-RPC messages. Ideal for local development and direct integration with MCP clients.\n\n### 2. StreamableHTTP Transport\nModern HTTP-based transport supporting both direct HTTP requests and Server-Sent Events (SSE) streams. This is the recommended transport for remote/distributed setups.\n\n**Features:**\n- **Endpoint**: `http://{hostname}:8080/mcp`\n- **Health Check**: `http://{hostname}:8080/health`\n- **Environment Configuration**: Set `TRANSPORT_MODE=streamable-http` or `TRANSPORT_PORT=8080` to enable\n\n**Environment Variables:**\n\n| Variable | Description                                                                                                                                   | Default                 |\n|----------|-----------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|\n| `TRANSPORT_MODE` | Set to `streamable-http` to enable HTTP transport (legacy `http` value still supported)                                                       | `stdio`                 |\n| `TRANSPORT_HOST` | Host to bind the HTTP server                                                                                                                  | `127.0.0.1`             |\n| `TRANSPORT_PORT` | HTTP server port                                                                                                                              | `8080`                  |\n| `MCP_ENDPOINT` | HTTP server endpoint path                                                                                                                     | `/mcp`                  |\n| `MCP_SESSION_MODE` | Session mode: `stateful` or `stateless`                                                                                                       | `stateful`              |\n| `MCP_ALLOWED_ORIGINS` | Comma-separated list of allowed origins for CORS                                                                                              | `\"\"` (empty)            |\n| `MCP_CORS_MODE` | CORS mode: `strict`, `development`, or `disabled`                                                                                             | `strict`                |\n| `CONSUL_HTTP_ADDR` | Consul agent HTTP API address                                                                                                                 | `http://127.0.0.1:8500` |\n| `CONSUL_HTTP_TOKEN` | Consul ACL token for authentication                                                                                                           | `\"\"` (empty)            |\n| `CONSUL_SKIP_VERIFY` | Skip TLS certificate verification (use only for development/testing)                                                                          | `false`                 |\n| `CONSUL_ENTERPRISE` | Enable Consul Enterprise features and API endpoints                                                                                           | `true`                   |\n| `CONSUL_MCP_SERVER_READ_GITHUB_RESOURCES` | For latest Consul context, the flag enables the fetching resource from https://github.com/hashicorp/consul/blob/main/website/content/api-docs | `true`                  |\n\n## TLS Configuration\n\nThe Consul MCP Server supports secure connections to Consul clusters with proper TLS configuration. Here are the key settings:\n\n### Certificate Verification\n\nBy default, the MCP server verifies TLS certificates when connecting to HTTPS Consul endpoints. If your Consul cluster uses self-signed certificates or certificates that cannot be verified against the system's certificate store, you may encounter errors like:\n\n```\ntls: failed to verify certificate: x509: \"________\" certificate is not trusted\n```\n\n### Disabling Certificate Verification (Development/Testing Only)\n\n**⚠️ Security Warning**: Only disable certificate verification in development or testing environments. Never use this in production.\n\nTo disable TLS certificate verification, set the environment variable:\n\n```bash\nexport CONSUL_SKIP_VERIFY=true\n```\n\n### Example Configurations for Development\n\n**Development with self-signed certificates:**\n```bash\nexport CONSUL_HTTP_ADDR=https://consul.example.com:8501\nexport CONSUL_HTTP_TOKEN=your-acl-token\nexport CONSUL_SKIP_VERIFY=true\n```\n\n**Production with proper certificates:**\n```bash\nexport CONSUL_HTTP_ADDR=https://consul.example.com:8501\nexport CONSUL_HTTP_TOKEN=your-acl-token\nexport CONSUL_SKIP_VERIFY=false\n# CONSUL_SKIP_VERIFY should remain false (default)\n```\n\n**Docker example with TLS skip verification:**\n```bash\ndocker run -i --rm \\\n  -e CONSUL_HTTP_ADDR=https://host.docker.internal:8501 \\\n  -e CONSUL_HTTP_TOKEN=your-token \\\n  -e CONSUL_SKIP_VERIFY=true \\\n  hashicorp/consul-mcp-server\n```\n\n## Command Line Options\n\n```bash\n# Download the Binary\n# Find the compatible build for your operating system from the official releases page.\n# e.g. for Mac Apple silicon\ncurl -LO https://releases.hashicorp.com/consul-mcp-server/0.1.1/consul-mcp-server_0.1.1_darwin_arm64.zip \u0026\u0026 unzip ./consul-mcp-server_0.1.1_darwin_arm64.zip\n\n# common step to start the server\nexport CONSUL_HTTP_ADDR=\u003cconsul addr\u003e\nexport CONSUL_HTTP_TOKEN=\u003cconsul double default acl token with read privilege\u003e\n./consul-mcp-server streamable-http --transport-port \u003c8080 default\u003e --transport-host 0.0.0.0\n\n\n# Stdio mode\nconsul-mcp-server stdio [--log-file /path/to/log]\n\n# StreamableHTTP mode\nconsul-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--log-file /path/to/log]\n```\n\n## Session Modes\n\nThe Consul MCP Server supports two session modes when using the StreamableHTTP transport:\n\n- **Stateful Mode (Default)**: Maintains session state between requests, enabling context-aware operations.\n- **Stateless Mode**: Each request is processed independently without maintaining session state, which can be useful for high-availability deployments or when using load balancers.\n\nTo enable stateless mode, set the environment variable:\n```bash\nexport MCP_SESSION_MODE=stateless\n```\n\n## Installation\n\n### Usage with VS Code\n\nAdd the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`. \n\nMore about using MCP server tools in VS Code's [agent mode documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"consul\": {\n        \"command\": \"docker\",\n        \"args\": [\n          \"run\",\n          \"-i\",\n          \"--rm\",\n          \"-e\", \"CONSUL_HTTP_ADDR=http://host.docker.internal:8500\",\n          \"hashicorp/consul-mcp-server\"\n        ]\n      }\n    }\n  }\n}\n```\n\nOptionally, you can add a similar example (i.e. without the mcp key) to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.\n\n```json\n{\n  \"servers\": {\n    \"consul\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-e\", \"CONSUL_HTTP_ADDR=http://host.docker.internal:8500\",\n        \"hashicorp/consul-mcp-server\"\n      ]\n    }\n  }\n}\n```\n\nCopilot client mode\n\n```json\n{\n  servers: {\n    \"consul-cluster-dc1\": {\n      \"url\": \"http://\u003cmcp-server-dc1-address\u003e:\u003cport\u003e\",\n      \"headers\": {\n        \"X-Consul-Address\": \"\u003cconsul-address-dc1\u003e\",\n        \"X-Consul-Token\": \"\u003cconsul-acl-token-dc1\u003e\"\n      }\n    },\n    \"consul-cluster-dc2\": {\n      \"url\": \"http://\u003cmcp-server-dc2-address\u003e:\u003cport\u003e\",\n      \"headers\": {\n        \"X-Consul-Address\": \"\u003cconsul-address-dc2\u003e\",\n        \"X-Consul-Token\": \"\u003cconsul-acl-token-dc2\u003e\"\n      }\n    }\n  },\n  \"inputs\": []\n}\n```\n\n### Usage with Claude Desktop / Amazon Q Developer / Amazon Q CLI\n\nMore about using MCP server tools in Claude Desktop [user documentation](https://modelcontextprotocol.io/quickstart/user).\nRead more about using MCP server in Amazon Q from the [documentation](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/qdev-mcp.html).\n\n```json\n{\n  \"mcpServers\": {\n    \"consul-dc1\": {\n      \"command\": \"consul-mcp-server\",\n      \"args\": [\"--host\", \"localhost\", \"--port\", \"8080\"],\n      \"env\": {\n        \"CONSUL_HTTP_ADDR\": \"https://consul-dc1.example.com:8501\",\n        \"CONSUL_HTTP_TOKEN\": \"${CONSUL_DC1_TOKEN}\"\n      }\n    },\n    \"consul-dc2\": {\n      \"command\": \"consul-mcp-server\",\n      \"args\": [\"--host\", \"localhost\", \"--port\", \"8081\"],\n      \"env\": {\n        \"CONSUL_HTTP_ADDR\": \"https://consul-dc2.example.com:8501\",\n        \"CONSUL_HTTP_TOKEN\": \"${CONSUL_DC2_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\n## Tool Configuration\n\n### Available Toolsets\n\nThe following sets of tools are available for interacting with Consul:\n\n| Toolset | Tools | Description |\n|---------|-------|-------------|\n| `catalog` | `get_catalog_services`, `get_catalog_nodes`, `get_catalog_service`, `get_catalog_connect`, `get_catalog_node`, `get_catalog_datacenters`, `get_catalog_gateway_services` | Query and explore services and nodes in the Consul catalog |\n| `agent` | `get_agent_self`, `get_agent_config`, `get_agent_members`, `get_agent_metrics`, `get_agent_host`, `get_agent_version`, `get_agent_reload` | Monitor and configure Consul agents |\n| `health` | `get_health_node`, `get_health_checks`, `get_health_service`, `get_health_connect`, `get_health_ingress`, `get_health_state` | Query health information for services and nodes |\n| `kv` | `get_kv`, `get_kv_keys`, `get_kv_recursive` | Access and manage the Consul key-value store |\n| `acl` | `get_acl_tokens`, `get_acl_policies`, `get_acl_roles`, `get_acl_auth_methods`, `get_acl_binding_rules`, `get_acl_templated_policies` | Manage Access Control Lists and authentication |\n| `connect` | `get_connect_ca_roots`, `get_connect_ca_configuration`, `get_connect_intentions`, `get_connect_intention`, `get_connect_intention_match`, `get_connect_intention_check` | Manage Consul Connect service mesh features |\n| `operator` | `get_operator_autopilot_*`, `get_operator_keyring`, `get_operator_license`, `get_operator_raft_*`, `get_operator_usage` | Access cluster operational tools and configuration |\n| `session` | `get_session`, `get_session_node`, `get_session_list` | Manage Consul sessions for distributed locking |\n| `status` | `get_status_leader`, `get_status_peers` | Query cluster status and leadership information |\n| `peering` | `get_peerings`, `get_peering`, `get_peering_exported_services` | Manage cluster peering relationships |\n| `config` | `get_config_entries`, `get_config_entry` | Access Consul configuration entries |\n| `discovery` | `get_discovery_chain` | Query service discovery chains |\n| `query` | `get_query`, `get_query_by_id`, `get_query_execute`, `get_query_explain` | Execute and manage prepared queries |\n| `namespaces` | `get_namespaces`, `get_namespace` | Manage Consul Enterprise namespaces (Enterprise only) |\n| `identity` | Various identity-related tools | Manage service identity and certificates |\n\n## Resource Configuration\n\n### Available Resources\n\n| Resource URI | Description |\n|--------------|-------------|\n| `consul://connect/ca/roots` | Consul Cluster Identity - Provides access to the Consul Connect CA root certificates and cluster identity information |\n| `consul://api-docs/*` | Consul API Documentation - Dynamic access to official Consul API documentation from the GitHub repository |\n\n### Install from source\n\nUse the latest release version:\n\n```console\ngo install github.com/hashicorp/consul-mcp-server/cmd/consul-mcp-server@latest\n```\n\nUse the main branch:\n\n```console\ngo install github.com/hashicorp/consul-mcp-server/cmd/consul-mcp-server@main\n```\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"consul\": {\n        \"command\": \"/path/to/consul-mcp-server\",\n        \"args\": [\"stdio\"]\n      }\n    }\n  }\n}\n```\n\n## Contributing\n\nThank you for your interest in contributing! Please refer to [CONTRIBUTING.md](https://github.com/hashicorp/consul-mcp-server/blob/main/CONTRIBUTING.md)\n\n## License\n\nThis project is licensed under the terms of the Business Source License 1.1. Please refer to the [LICENSE](./LICENSE) file for the full terms.\n\n## Security\n\nFor security issues, please contact security@hashicorp.com or follow our [security policy](https://www.hashicorp.com/en/trust/security/vulnerability-management).\n\n## Support\n\nFor bug reports and feature requests, please open an issue on GitHub.\n\nFor general questions and discussions, open a GitHub Discussion.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhashicorp%2Fconsul-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhashicorp%2Fconsul-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhashicorp%2Fconsul-mcp-server/lists"}