# 🔐 env-mcp - Environment Variable MCP Server

> A Model Context Protocol (MCP) server for secure environment variable and configuration management with Claude Code integration

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
[![Built by BuildAppolis](https://img.shields.io/badge/Built%20by-BuildAppolis-purple)](https://buildappolis.com)

## Features

- **Secure Storage**: Store environment variables with optional sensitive data protection
- **Categories**: Organize variables by category for better management
- **Search & Filter**: Find variables quickly with search functionality
- **Multiple Formats**: Export/import support for .env, JSON, and YAML formats
- **MCP Integration**: Seamlessly integrates with Claude Code for AI-assisted configuration management
- **CLI Tool**: Powerful command-line interface for manual management

## Installation

```bash
# Clone the repository
git clone https://github.com/buildappolis/env-mcp.git
cd env-mcp

# Install dependencies
pnpm install

# Build the project
pnpm run build
```

## Configuration

### Add to Claude Code

The server is already configured with Claude Code. To verify:

```bash
claude mcp list
```

You should see:
```
env-mcp: node /home/cory-ubuntu/coding/env-mcp/dist/index.js - ✓ Connected
```

### Manual Configuration

If you need to reconfigure:

```bash
claude mcp add env-mcp "node" "/path/to/env-mcp/dist/index.js"
```

## CLI Usage

### Basic Commands

```bash
# Set a variable
./env-mcp-cli set KEY "value" --description "Description" --category "category"

# Set a sensitive variable (will be redacted in output)
./env-mcp-cli set API_KEY "secret" --sensitive --category "secrets"

# Get a variable
./env-mcp-cli get KEY

# List all variables
./env-mcp-cli list

# List by category
./env-mcp-cli list --category "secrets"

# Search variables
./env-mcp-cli search "api"

# Delete a variable
./env-mcp-cli delete KEY

# List categories
./env-mcp-cli categories
```

### Import/Export

```bash
# Export to .env format
./env-mcp-cli export --format env --output .env

# Export to JSON
./env-mcp-cli export --format json --output config.json

# Export to YAML
./env-mcp-cli export --format yaml --output config.yaml

# Import from .env file
./env-mcp-cli import .env
```

## MCP Tools (Available in Claude)

When using Claude Code, the following tools are available:

- `env_get` - Get an environment variable value
- `env_set` - Set an environment variable with optional metadata
- `env_delete` - Delete an environment variable
- `env_search` - Search for variables by query
- `env_list` - List all variables or filter by category
- `env_export` - Export variables in different formats
- `env_import` - Import variables from a file

## Data Storage

Configuration is stored in: `~/.env-mcp/config.yaml`

The storage format includes:
- Variable key/value pairs
- Optional descriptions
- Categories for organization
- Sensitive data flags
- Creation/update timestamps

## Examples

### Setting up a development environment

```bash
# Database configuration
./env-mcp-cli set DB_HOST "localhost" --category "database"
./env-mcp-cli set DB_PORT "5432" --category "database"
./env-mcp-cli set DB_NAME "myapp" --category "database"
./env-mcp-cli set DB_USER "admin" --category "database"
./env-mcp-cli set DB_PASS "secret" --sensitive --category "database"

# API Keys
./env-mcp-cli set OPENAI_API_KEY "sk-..." --sensitive --category "api-keys"
./env-mcp-cli set STRIPE_API_KEY "sk_test_..." --sensitive --category "api-keys"

# Application settings
./env-mcp-cli set NODE_ENV "development" --category "app"
./env-mcp-cli set PORT "3000" --category "app"
./env-mcp-cli set LOG_LEVEL "debug" --category "app"

# Export for use in application
./env-mcp-cli export --format env --output .env
```

### Searching and filtering

```bash
# Find all database-related variables
./env-mcp-cli search "db"

# List all API keys
./env-mcp-cli list --category "api-keys"

# Show all categories
./env-mcp-cli categories
```

### JSON output for scripting

```bash
# Get JSON output for parsing
./env-mcp-cli list --json | jq '.[] | select(.category == "database")'

# Export specific category to JSON
./env-mcp-cli list --category "app" --json > app-config.json
```

## Security

- Variables marked as `--sensitive` are redacted in normal output
- Use `--show-sensitive` flag with `get` command to view sensitive values
- Sensitive values are still exported normally (be careful with exports)
- Configuration file permissions should be restricted (chmod 600)

## Development

### Project Structure

```
env-mcp/
├── src/
│   ├── index.ts       # MCP server implementation
│   ├── cli.ts         # CLI tool implementation
│   ├── store.ts       # Storage layer
│   └── types.ts       # TypeScript type definitions
├── dist/              # Compiled JavaScript
├── package.json       # Dependencies and scripts
└── tsconfig.json      # TypeScript configuration
```

### Scripts

```bash
# Build the project
pnpm run build

# Run in development mode
pnpm run dev

# Run CLI in development
pnpm run cli
```

## Troubleshooting

### MCP Server won't connect

1. Check if the server is built:
   ```bash
   pnpm run build
   ```

2. Test the server manually:
   ```bash
   echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | node dist/index.js
   ```

3. Reconnect with Claude:
   ```bash
   claude mcp list  # Check status
   ```

### Variables not persisting

Check the configuration file:
```bash
cat ~/.env-mcp/config.yaml
```

Ensure write permissions:
```bash
mkdir -p ~/.env-mcp
chmod 755 ~/.env-mcp
```

## License

MIT

## Contributing

Feel free to submit issues and pull requests to improve the env-mcp server.