{"_id":"@abhishek8380/qconsul-mcp-server","_rev":"3-d87cb4a500ae8aa072cd971af6e0fb92","name":"@abhishek8380/qconsul-mcp-server","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@abhishek8380/qconsul-mcp-server","version":"1.0.0","keywords":["mcp","consul","qconsul","kv","key-value","stdio","model-context-protocol","windsurf","hashicorp"],"author":{"name":"Abhishek Bhadane"},"license":"MIT","_id":"@abhishek8380/qconsul-mcp-server@1.0.0","maintainers":[{"name":"abhishek8380","email":"abhishekbhadane838@gmail.com"}],"bin":{"qconsul-mcp":"server.js"},"dist":{"shasum":"aa941cff34749b20520b449c42c1923e24ac3efa","tarball":"https://registry.npmjs.org/@abhishek8380/qconsul-mcp-server/-/qconsul-mcp-server-1.0.0.tgz","fileCount":4,"integrity":"sha512-DfX53rlzieAZ/QDq1A4DU03SotUE145g0pFh81wu3uik1SL+A3c98sEuYdvCGkzsMMJvmcTwr6YmSE1wpu9Qaw==","signatures":[{"sig":"MEUCIDng781n4NuoQXZjsh5ubwWam/IuhLV21EXUFxv4sjWtAiEA6LgENvh/sUy0LbrF7HQl1fpcqMovnjMn7ubnuiLZ49E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":26534},"main":"server.js","type":"module","engines":{"node":">=18.0.0"},"scripts":{"start":"node server.js"},"_npmUser":{"name":"abhishek8380","email":"abhishekbhadane838@gmail.com"},"_npmVersion":"10.9.3","description":"MCP server for Consul KV store operations (get, put, delete, list keys)","directories":{},"_nodeVersion":"22.19.0","dependencies":{"zod":"^3.22.4","dotenv":"^16.3.1","node-fetch":"^3.3.2","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/qconsul-mcp-server_1.0.0_1776172153171_0.03282908107022098","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@abhishek8380/qconsul-mcp-server","version":"1.1.0","keywords":["mcp","consul","qconsul","kv","key-value","stdio","model-context-protocol","windsurf","hashicorp"],"author":{"name":"Abhishek Bhadane"},"license":"MIT","_id":"@abhishek8380/qconsul-mcp-server@1.1.0","maintainers":[{"name":"abhishek8380","email":"abhishekbhadane838@gmail.com"}],"bin":{"qconsul-mcp":"server.js"},"dist":{"shasum":"14a12930de77b81f216577d8200dc86d8efb9e07","tarball":"https://registry.npmjs.org/@abhishek8380/qconsul-mcp-server/-/qconsul-mcp-server-1.1.0.tgz","fileCount":4,"integrity":"sha512-VcI8ukWrVPXDViVqDghaL6YoAboiUsLnt42FBTDfxiJrKcQ57VD5CXdsymYRbj4aPfJX8z+GBf9zbAt3c7MrLg==","signatures":[{"sig":"MEUCIQDR60SXXr2D12jPN46MQ7Zh9ufAz1op86YVwFEnmXvtwwIgXwj+We2yjQhRBzWj4tYbp1Z/9W7L1/a/aCTg8dxi+os=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31666},"main":"server.js","type":"module","engines":{"node":">=18.0.0"},"scripts":{"start":"node server.js"},"_npmUser":{"name":"abhishek8380","email":"abhishekbhadane838@gmail.com"},"_npmVersion":"10.9.3","description":"MCP server for Consul KV store operations (get, put, delete, list keys)","directories":{},"_nodeVersion":"22.19.0","dependencies":{"zod":"^3.22.4","dotenv":"^16.3.1","node-fetch":"^3.3.2","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/qconsul-mcp-server_1.1.0_1776244119476_0.9555790521927603","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@abhishek8380/qconsul-mcp-server","version":"1.1.1","type":"module","description":"MCP server for Consul KV store operations (get, put, delete, list keys)","main":"server.js","bin":{"qconsul-mcp":"server.js"},"scripts":{"start":"node server.js"},"keywords":["mcp","consul","qconsul","kv","key-value","stdio","model-context-protocol","windsurf","hashicorp"],"author":{"name":"Abhishek Bhadane"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","node-fetch":"^3.3.2","dotenv":"^16.3.1","zod":"^3.22.4"},"engines":{"node":">=18.0.0"},"_id":"@abhishek8380/qconsul-mcp-server@1.1.1","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-edSVagmctjsg2mr2WxkgBa/7Z0bCZNImvCi/qz2iwYWzJ/MhVPitMrhlbI2T8aXDQ9EKYzVOgenX3zkM7AXfUg==","shasum":"a34472257a259be646e9965275644ce147e43903","tarball":"https://registry.npmjs.org/@abhishek8380/qconsul-mcp-server/-/qconsul-mcp-server-1.1.1.tgz","fileCount":3,"unpackedSize":31049,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDQqBx4JeZHe4x7yodLKye3bBlbE8o+J/lkIU+i1fIh0AiBvtzxLau3+6MZAkM0TCoWtpjWZWY2ypSR3f7i0vx18NQ=="}]},"_npmUser":{"name":"abhishek8380","email":"abhishekbhadane838@gmail.com"},"directories":{},"maintainers":[{"name":"abhishek8380","email":"abhishekbhadane838@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/qconsul-mcp-server_1.1.1_1778825362245_0.5110001206279235"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-14T13:09:13.026Z","modified":"2026-05-15T06:09:22.495Z","1.0.0":"2026-04-14T13:09:13.322Z","1.1.0":"2026-04-15T09:08:39.627Z","1.1.1":"2026-05-15T06:09:22.382Z"},"author":{"name":"Abhishek Bhadane"},"license":"MIT","keywords":["mcp","consul","qconsul","kv","key-value","stdio","model-context-protocol","windsurf","hashicorp"],"description":"MCP server for Consul KV store operations (get, put, delete, list keys)","maintainers":[{"name":"abhishek8380","email":"abhishekbhadane838@gmail.com"}],"readme":"# Consul KV MCP Server\n\nA 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.\n\n**Built for infrastructure teams** to manage Consul KV configurations seamlessly.\n\n## Features\n\n- 🔍 **Search and list keys** - Discover keys with prefix matching and search\n- 📖 **Read key values** - Get individual or recursive key-value pairs\n- ✏️ **Create/Update keys** - Set or modify key-value pairs\n- 🗑️ **Delete keys** - Remove single keys or entire prefixes recursively\n- 🔐 **HTTP Basic Authentication** - Secure access with username/password\n- 🧠 **Dual naming** - Every tool available under both `*` and `qconsul_*` aliases\n- 🚀 **Zero installation** - Use with npx in your MCP client configuration\n\n## Use Case\n\nThis MCP server is designed for teams using Consul KV store for configuration management. It allows you to:\n\n- **Update configuration files** directly from your IDE without switching to the Consul UI\n- **Search and discover** configuration keys across your infrastructure\n- **Bulk operations** on configuration hierarchies\n- **Version control integration** - Make config changes alongside code changes\n\nPerfect for DevOps teams managing microservices configuration in Consul.\n\n## Installation\n\nNo installation required! Use with npx in your MCP client configuration.\n\n## Configuration for Windsurf\n\nAdd this to your Windsurf MCP configuration file (`~/.codeium/windsurf/mcp_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"qconsul\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abhishek8380/qconsul-mcp-server\"],\n      \"env\": {\n        \"CONSUL_URL\": \"https://consul.example.com\",\n        \"CONSUL_USERNAME\": \"your-username\",\n        \"CONSUL_PASSWORD\": \"your-password\",\n        \"CONSUL_DATACENTER\": \"dc1\"\n      }\n    }\n  }\n}\n```\n\n### Environment Variables\n\n- `CONSUL_URL` - Your Consul instance URL (e.g., `https://consul.example.com`)\n- `CONSUL_USERNAME` - HTTP Basic Auth username (required)\n- `CONSUL_PASSWORD` - HTTP Basic Auth password (required)\n- `CONSUL_DATACENTER` - Default datacenter to use (e.g., `dc1`, `us-east-1`)\n\n## Configuration for Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"qconsul\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abhishek8380/qconsul-mcp-server\"],\n      \"env\": {\n        \"CONSUL_URL\": \"https://consul.example.com\",\n        \"CONSUL_USERNAME\": \"your-username\",\n        \"CONSUL_PASSWORD\": \"your-password\",\n        \"CONSUL_DATACENTER\": \"dc1\"\n      }\n    }\n  }\n}\n```\n\n## Available Tools\n\nEvery tool below can be called with either its standard name or the `qconsul_*` alias shown in parentheses.\n\n### Read Operations\n\n#### **get_key** (`qconsul_get_key`)\nRetrieve a value from Consul KV store by key path.\n\n**Parameters:**\n- `key` (string, required) - The key path to retrieve (e.g., `myapp/config/setting`)\n- `raw` (boolean, optional) - Return raw value without metadata (default: `false`)\n- `datacenter` (string, optional) - Datacenter to query\n\n**Example:**\n```javascript\n{\n  \"key\": \"myapp/config/database\",\n  \"raw\": false\n}\n```\n\n#### **list_keys** (`qconsul_list_keys`)\nList all keys under a prefix in Consul KV store.\n\n**Parameters:**\n- `prefix` (string, optional) - Key prefix to list (empty for all keys)\n- `separator` (string, optional) - Separator for grouping keys (e.g., `/`)\n- `datacenter` (string, optional) - Datacenter to query\n\n**Example:**\n```javascript\n{\n  \"prefix\": \"myapp/\",\n  \"separator\": \"/\"\n}\n```\n\n#### **get_keys_recursive** (`qconsul_get_keys_recursive`)\nRetrieve all key-value pairs under a prefix recursively.\n\n**Parameters:**\n- `prefix` (string, optional) - Key prefix to retrieve (empty for all keys)\n- `datacenter` (string, optional) - Datacenter to query\n\n**Example:**\n```javascript\n{\n  \"prefix\": \"myapp/config/\"\n}\n```\n\n#### **search_keys** (`qconsul_search_keys`)\nSearch for keys matching a pattern in Consul KV store.\n\n**Parameters:**\n- `searchTerm` (string, required) - Search term to find in key names\n- `prefix` (string, optional) - Optional prefix to narrow search scope\n- `datacenter` (string, optional) - Datacenter to query\n\n**Example:**\n```javascript\n{\n  \"searchTerm\": \"database\",\n  \"prefix\": \"myapp/\"\n}\n```\n\n### Write Operations\n\n#### **put_key** (`qconsul_put_key`)\nCreate or update a key-value pair in Consul KV store.\n\n**Parameters:**\n- `key` (string, required) - The key path to create/update (e.g., `myapp/config/setting`)\n- `value` (string, required) - The value to store\n- `datacenter` (string, optional) - Datacenter to use\n- `flags` (number, optional) - Optional flags for the key (default: `0`)\n\n**Example:**\n```javascript\n{\n  \"key\": \"myapp/config/timeout\",\n  \"value\": \"30\"\n}\n```\n\n### Delete Operations\n\n#### **delete_key** (`qconsul_delete_key`)\nDelete a key or keys from Consul KV store.\n\n**Parameters:**\n- `key` (string, required) - The key path to delete\n- `recurse` (boolean, optional) - Delete all keys with this prefix (default: `false`)\n- `datacenter` (string, optional) - Datacenter to use\n\n**Example:**\n```javascript\n{\n  \"key\": \"myapp/config/old-setting\",\n  \"recurse\": false\n}\n```\n\n## How to Use - CRUD Operations Guide\n\n### 1. **CREATE** - Add New Configuration\n\n**Create a single key:**\n```\nAsk: \"Create a new key myapp/config/new-feature with value 'enabled'\"\n```\n\n**Create multiple keys (bulk upload):**\n```\nAsk: \"Create these keys under myapp/services/:\n- config.yml with database settings\n- kafka-client.yml with broker configs\n- application.properties with app settings\"\n```\n\n**What happens:** The MCP server uses `put_key` to create new entries in Consul KV store.\n\n---\n\n### 2. **READ** - Retrieve Configuration\n\n**Read a single key:**\n```\nAsk: \"Get the value of myapp/config/database\"\nAsk: \"Show me myapp/services/application.yml\"\n```\n\n**List all keys under a prefix:**\n```\nAsk: \"List all keys under myapp/\"\nAsk: \"Show me all configuration files in myapp/services/\"\n```\n\n**Search for specific keys:**\n```\nAsk: \"Search for keys containing 'database' in myapp\"\nAsk: \"Find all kafka configuration keys\"\n```\n\n**Get all keys recursively with values:**\n```\nAsk: \"Get all key-value pairs under myapp/config/\"\n```\n\n**What happens:** The MCP server uses `get_key`, `list_keys`, `search_keys`, or `get_keys_recursive` to fetch data.\n\n---\n\n### 3. **UPDATE** - Modify Existing Configuration\n\n**Update a single value:**\n```\nAsk: \"Update myapp/config/timeout to 60\"\nAsk: \"Change the version in myapp/services/application.yml to 2.8.0\"\n```\n\n**Update entire file:**\n```\nAsk: \"Update myapp/config/database.yml with this content:\nhost: db.example.com\nport: 5432\nusername: dbuser\"\n```\n\n**What happens:** The MCP server:\n1. Reads the current value (if needed)\n2. Modifies the specific field or replaces entire content\n3. Uses `put_key` to update the value in Consul\n\n---\n\n### 4. **DELETE** - Remove Configuration\n\n**Delete a single key:**\n```\nAsk: \"Delete the key myapp/config/deprecated-setting\"\n```\n\n**Delete all keys under a prefix (recursive):**\n```\nAsk: \"Delete all keys under myapp/old-service/ recursively\"\n```\n\n**What happens:** The MCP server uses `delete_key` with optional `recurse` parameter.\n\n---\n\n## Complete Example Workflow\n\n### Scenario: Managing a new microservice configuration\n\n**Step 1: Discover existing structure**\n```\nAsk: \"List all keys under myapp/\"\n```\n\n**Step 2: Create new service configuration**\n```\nAsk: \"Create myapp/my-service/application.yml with:\nserver:\n  port: 8080\ndatabase:\n  url: jdbc:postgresql://localhost:5432/mydb\"\n```\n\n**Step 3: Verify creation**\n```\nAsk: \"Get the value of myapp/my-service/application.yml\"\n```\n\n**Step 4: Update a specific value**\n```\nAsk: \"Update the port in myapp/my-service/application.yml to 9090\"\n```\n\n**Step 5: Add more configuration files**\n```\nAsk: \"Create myapp/my-service/kafka-client.yml with broker configs\"\n```\n\n**Step 6: List all service configs**\n```\nAsk: \"List all keys under myapp/my-service/\"\n```\n\n**Step 7: Clean up (if needed)**\n```\nAsk: \"Delete myapp/my-service/old-config.yml\"\n```\n\n## Authentication\n\nThis server uses **HTTP Basic Authentication** to connect to your Consul instance. The credentials are passed via environment variables:\n\n- Username and password are base64-encoded and sent in the `Authorization` header\n- Ensure your Consul instance is configured to accept Basic Auth\n- For production use, consider using ACL tokens instead of basic auth\n\n## Consul KV Hierarchy\n\nConsul KV uses a hierarchical key structure with `/` as the separator:\n\n```\nmyapp/\n  ├── config/\n  │   ├── database\n  │   ├── timeout\n  │   └── api-key\n  ├── features/\n  │   ├── feature-a\n  │   └── feature-b\n  └── metadata/\n      └── version\n```\n\nKeys are case-sensitive and can contain any UTF-8 characters.\n\n## Local Development\n\n1. Clone the repository\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Create `.env` file:\n   ```bash\n   cp .env.example .env\n   # Edit .env with your credentials\n   ```\n\n4. Run the server:\n   ```bash\n   npm start\n   ```\n\n## Testing the Server\n\nYou can test the server locally using the MCP Inspector or by configuring it in Windsurf/Claude Desktop.\n\n### Example Commands\n\n```bash\n# List all keys\ncurl -u username:password https://consul.example.com/v1/kv/?keys=true\n\n# Get a specific key\ncurl -u username:password https://consul.example.com/v1/kv/myapp/config/setting\n\n# Put a key\ncurl -u username:password -X PUT -d \"value\" https://consul.example.com/v1/kv/myapp/config/setting\n\n# Delete a key\ncurl -u username:password -X DELETE https://consul.example.com/v1/kv/myapp/config/setting\n```\n\n## Security Considerations\n\n- **Never commit credentials** - Use environment variables or secure secret management\n- **Use HTTPS** - Always connect to Consul over HTTPS in production\n- **ACL Tokens** - Consider using Consul ACL tokens instead of basic auth for production\n- **Least Privilege** - Grant only necessary permissions to the MCP server\n\n## Troubleshooting\n\n### Connection Issues\n- Verify `CONSUL_URL` is correct and accessible\n- Check that your credentials are valid\n- Ensure your network allows access to the Consul instance\n\n### Authentication Errors\n- Confirm username and password are correct\n- Check if Consul requires ACL tokens instead of basic auth\n\n### Key Not Found\n- Verify the key path is correct (case-sensitive)\n- Use `list_keys` to discover available keys\n- Check the datacenter parameter if using multiple datacenters\n\n## API Reference\n\nThis server implements the Consul KV HTTP API:\n- [Consul KV Store API Documentation](https://developer.hashicorp.com/consul/api-docs/kv)\n- [Consul KV CLI Reference](https://developer.hashicorp.com/consul/commands/kv)\n\n## License\n\nMIT\n\n## Author\n\nAbhishek Bhadane\n\n## Package\n\nhttps://www.npmjs.com/package/@abhishek8380/qconsul-mcp-server\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: [Create an issue](https://github.com/yourusername/qconsul-mcp-server/issues)\n- Documentation: [Consul KV Store](https://developer.hashicorp.com/consul/docs/automate/kv)\n","readmeFilename":"README.md"}