Qualys QConsul MCP Server

A Model Context Protocol (MCP) server for HashiCorp Consul KV store operations. This server enables AI assistants to interact with Consul's key-value store through a standardized interface, allowing you to read, write, update, and delete configuration values directly from your IDE.

Built for Qualys infrastructure teams to manage Consul KV configurations seamlessly.

Features

• 🔍 Search and list keys - Discover keys with prefix matching and search
• 📖 Read key values - Get individual or recursive key-value pairs
• ✏️ Create/Update keys - Set or modify key-value pairs
• 🗑️ Delete keys - Remove single keys or entire prefixes recursively
• 🔐 HTTP Basic Authentication - Secure access with username/password
• 🧠 Dual naming - Every tool available under both * and qconsul_* aliases
• 🚀 Zero installation - Use with npx in your MCP client configuration

Use Case

This MCP server is designed for teams using Consul KV store for configuration management. It allows you to:

• Update configuration files directly from your IDE without switching to the Consul UI
• Search and discover configuration keys across your infrastructure
• Bulk operations on configuration hierarchies
• Version control integration - Make config changes alongside code changes

Perfect for DevOps teams managing microservices configuration in Consul.

Installation

No installation required! Use with npx in your MCP client configuration.

Configuration for Windsurf

Add this to your Windsurf MCP configuration file (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "qconsul": {
      "command": "npx",
      "args": ["-y", "@abhishek8380/qconsul-mcp-server"],
      "env": {
        "CONSUL_URL": "https://qconsul.p19.eng.sjc01.qualys.com",
        "CONSUL_USERNAME": "your-username",
        "CONSUL_PASSWORD": "your-password",
        "CONSUL_DATACENTER": "eng-sjc01-p19"
      }
    }
  }
}

Environment Variables

• CONSUL_URL - Your Consul instance URL (e.g., https://qconsul.p19.eng.sjc01.qualys.com)
• CONSUL_USERNAME - HTTP Basic Auth username (required)
• CONSUL_PASSWORD - HTTP Basic Auth password (required)
• CONSUL_DATACENTER - Default datacenter to use (e.g., eng-sjc01-p19)

Configuration for Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "qconsul": {
      "command": "npx",
      "args": ["-y", "@abhishek8380/qconsul-mcp-server"],
      "env": {
        "CONSUL_URL": "https://qconsul.p19.eng.sjc01.qualys.com",
        "CONSUL_USERNAME": "your-username",
        "CONSUL_PASSWORD": "your-password",
        "CONSUL_DATACENTER": "eng-sjc01-p19"
      }
    }
  }
}

Available Tools

Every tool below can be called with either its standard name or the qconsul_* alias shown in parentheses.

Read Operations

get_key (qconsul_get_key)

Retrieve a value from Consul KV store by key path.

Parameters:

• key (string, required) - The key path to retrieve (e.g., cloudview/config/setting)
• raw (boolean, optional) - Return raw value without metadata (default: false)
• datacenter (string, optional) - Datacenter to query

Example:

{
  "key": "cloudview/config/database",
  "raw": false
}

list_keys (qconsul_list_keys)

List all keys under a prefix in Consul KV store.

Parameters:

• prefix (string, optional) - Key prefix to list (empty for all keys)
• separator (string, optional) - Separator for grouping keys (e.g., /)
• datacenter (string, optional) - Datacenter to query

Example:

{
  "prefix": "cloudview/",
  "separator": "/"
}

get_keys_recursive (qconsul_get_keys_recursive)

Retrieve all key-value pairs under a prefix recursively.

Parameters:

• prefix (string, optional) - Key prefix to retrieve (empty for all keys)
• datacenter (string, optional) - Datacenter to query

Example:

{
  "prefix": "cloudview/config/"
}

search_keys (qconsul_search_keys)

Search for keys matching a pattern in Consul KV store.

Parameters:

• searchTerm (string, required) - Search term to find in key names
• prefix (string, optional) - Optional prefix to narrow search scope
• datacenter (string, optional) - Datacenter to query

Example:

{
  "searchTerm": "database",
  "prefix": "cloudview/"
}

Write Operations

put_key (qconsul_put_key)

Create or update a key-value pair in Consul KV store.

Parameters:

• key (string, required) - The key path to create/update (e.g., cloudview/config/setting)
• value (string, required) - The value to store
• datacenter (string, optional) - Datacenter to use
• flags (number, optional) - Optional flags for the key (default: 0)

Example:

{
  "key": "cloudview/config/timeout",
  "value": "30"
}

Delete Operations

delete_key (qconsul_delete_key)

Delete a key or keys from Consul KV store.

Parameters:

• key (string, required) - The key path to delete
• recurse (boolean, optional) - Delete all keys with this prefix (default: false)
• datacenter (string, optional) - Datacenter to use

Example:

{
  "key": "cloudview/config/old-setting",
  "recurse": false
}

How to Use - CRUD Operations Guide

1. CREATE - Add New Configuration

Create a single key:

Ask: "Create a new key cloudview/config/new-feature with value 'enabled'"

Create multiple keys (bulk upload):

Ask: "Create these keys under cloudview/myapp/:
- config.yml with database settings
- kafka-client.yml with broker configs
- application.properties with app settings"

What happens: The MCP server uses put_key to create new entries in Consul KV store.

2. READ - Retrieve Configuration

Read a single key:

Ask: "Get the value of cloudview/config/database"
Ask: "Show me cloudview/gcp-service/application.yml"

List all keys under a prefix:

Ask: "List all keys under cloudview/"
Ask: "Show me all configuration files in cloudview/myapp/"

Search for specific keys:

Ask: "Search for keys containing 'database' in cloudview"
Ask: "Find all kafka configuration keys"

Get all keys recursively with values:

Ask: "Get all key-value pairs under cloudview/config/"

What happens: The MCP server uses get_key, list_keys, search_keys, or get_keys_recursive to fetch data.

3. UPDATE - Modify Existing Configuration

Update a single value:

Ask: "Update cloudview/config/timeout to 60"
Ask: "Change the version in cloudview/gcp-service/application.yml to 2.8.0"

Update entire file:

Ask: "Update cloudview/config/database.yml with this content:
host: db.example.com
port: 5432
username: dbuser"

What happens: The MCP server:

1. Reads the current value (if needed)
2. Modifies the specific field or replaces entire content
3. Uses put_key to update the value in Consul

4. DELETE - Remove Configuration

Delete a single key:

Ask: "Delete the key cloudview/config/deprecated-setting"

Delete all keys under a prefix (recursive):

Ask: "Delete all keys under cloudview/old-service/ recursively"

What happens: The MCP server uses delete_key with optional recurse parameter.

Complete Example Workflow

Scenario: Managing a new microservice configuration

Step 1: Discover existing structure

Ask: "List all keys under cloudview/"

Step 2: Create new service configuration

Ask: "Create cloudview/my-service/application.yml with:
server:
  port: 8080
database:
  url: jdbc:postgresql://localhost:5432/mydb"

Step 3: Verify creation

Ask: "Get the value of cloudview/my-service/application.yml"

Step 4: Update a specific value

Ask: "Update the port in cloudview/my-service/application.yml to 9090"

Step 5: Add more configuration files

Ask: "Create cloudview/my-service/kafka-client.yml with broker configs"

Step 6: List all service configs

Ask: "List all keys under cloudview/my-service/"

Step 7: Clean up (if needed)

Ask: "Delete cloudview/my-service/old-config.yml"

Authentication

This server uses HTTP Basic Authentication to connect to your Consul instance. The credentials are passed via environment variables:

• Username and password are base64-encoded and sent in the Authorization header
• Ensure your Consul instance is configured to accept Basic Auth
• For production use, consider using ACL tokens instead of basic auth

Consul KV Hierarchy

Consul KV uses a hierarchical key structure with / as the separator:

cloudview/
  ├── config/
  │   ├── database
  │   ├── timeout
  │   └── api-key
  ├── features/
  │   ├── feature-a
  │   └── feature-b
  └── metadata/
      └── version

Keys are case-sensitive and can contain any UTF-8 characters.

Local Development

1. Clone the repository

2. Install dependencies:

   npm install

3. Create .env file:

   cp .env.example .env
   # Edit .env with your credentials

4. Run the server:

   npm start

Testing the Server

You can test the server locally using the MCP Inspector or by configuring it in Windsurf/Claude Desktop.

Example Commands

# List all keys
curl -u username:password https://qconsul.p19.eng.sjc01.qualys.com/v1/kv/?keys=true

# Get a specific key
curl -u username:password https://qconsul.p19.eng.sjc01.qualys.com/v1/kv/cloudview/config/setting

# Put a key
curl -u username:password -X PUT -d "value" https://qconsul.p19.eng.sjc01.qualys.com/v1/kv/cloudview/config/setting

# Delete a key
curl -u username:password -X DELETE https://qconsul.p19.eng.sjc01.qualys.com/v1/kv/cloudview/config/setting

Security Considerations

• Never commit credentials - Use environment variables or secure secret management
• Use HTTPS - Always connect to Consul over HTTPS in production
• ACL Tokens - Consider using Consul ACL tokens instead of basic auth for production
• Least Privilege - Grant only necessary permissions to the MCP server

Troubleshooting

Connection Issues

• Verify CONSUL_URL is correct and accessible
• Check that your credentials are valid
• Ensure your network allows access to the Consul instance

Authentication Errors

• Confirm username and password are correct
• Check if Consul requires ACL tokens instead of basic auth

Key Not Found

• Verify the key path is correct (case-sensitive)
• Use list_keys to discover available keys
• Check the datacenter parameter if using multiple datacenters

API Reference

This server implements the Consul KV HTTP API:

• Consul KV Store API Documentation
• Consul KV CLI Reference

License

MIT

Author

Abhishek Bhadane

Package

https://www.npmjs.com/package/@abhishek8380/qconsul-mcp-server

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• GitHub Issues: Create an issue
• Documentation: Consul KV Store