MCPShield
Secure infrastructure access for AI agents — databases, APIs, cloud platforms, and more — with deterministic policy enforcement and comprehensive auditing.
Features
- MCP Server: Claude Code compatible stdio protocol
- Multi-Infrastructure Support: PostgreSQL, MySQL, SQLite, MongoDB, Redis — ready for APIs, cloud, and custom systems
- Fail-Closed Policy Engine: YAML-based security rules with default deny
- Centralized Policy Management: Policies authored in dashboard, automatically synced
- Audit Trail: Complete event logging to MCPShield control plane with policy_hash tracking
- Event Spooling: Never lose audit events, even when offline
- Developer-Friendly: Clear logs, helpful errors, easy configuration
Quick Start
Installation
pip install mcpshield
Super Quick Setup (Interactive)
The easiest way to get started:
mcpshield init
This interactive wizard will:
- Ask which infrastructure you want to secure (PostgreSQL, MySQL, SQLite, MongoDB, Redis)
- Configure your infrastructure connection
- Set up your MCPShield API key
- Automatically integrate with Claude Code and/or Cursor
- Guide you through policy creation
Setup (Environment Variables - Recommended)
No configuration file needed! Just set environment variables and run.
-
Create project and policy in MCPShield dashboard:
- Go to https://app.mcpshield.xyz
- Create project → Get Project ID
- Create policy → Define security rules
- Create API key
-
Set environment variables:
macOS/Linux:
export PG_DSN="postgresql://user:pass@localhost:5432/dbname" export MCPSHIELD_API_KEY="mcps_your_key" export PROJECT_ID="proj_your_id" export API_BASE_URL="https://api.mcpshield.xyz" # Optional, this is the default
Windows (PowerShell):
$env:PG_DSN = "postgresql://user:pass@localhost:5432/dbname" $env:MCPSHIELD_API_KEY = "mcps_your_key" $env:PROJECT_ID = "proj_your_id" $env:API_BASE_URL = "https://api.mcpshield.xyz" # Optional, this is the default
Or use a .env file:
# .env PG_DSN=postgresql://user:pass@localhost:5432/dbname MCPSHIELD_API_KEY=mcps_your_key PROJECT_ID=proj_your_id API_BASE_URL=https://api.mcpshield.xyz POLICY_SOURCE=remote
-
Verify setup:
mcpshield doctor # Or with .env file: mcpshield doctor --env-file .env
-
Run the gateway:
mcpshield serve # Or with .env file: mcpshield serve --env-file .env
Setup (YAML Config - Optional)
For advanced users who prefer a configuration file, you can create mcpshield.yaml:
database:
dsn: null # Set via PG_DSN env var
api:
base_url: "https://api.mcpshield.xyz"
project_id: null # Set via PROJECT_ID env var
api_key: null # Set via MCPSHIELD_API_KEY env var
policy:
source: "remote"
refresh_seconds: 60
# Optional: local policy file for fallback
# policy:
# source: "remote_with_fallback"
# file: "policy.yaml"
Then run with --config:
mcpshield doctor --config mcpshield.yaml
mcpshield serve --config mcpshield.yaml
Claude Code Integration
Add to your Claude Code MCP configuration (~/.claude/mcp.json):
Option 1: Environment Variables Only (Recommended)
{
"mcpServers": {
"mcpshield": {
"command": "mcpshield",
"args": ["serve"],
"env": {
"PG_DSN": "postgresql://user:pass@localhost:5432/db",
"MCPSHIELD_API_KEY": "mcps_...",
"PROJECT_ID": "proj_...",
"API_BASE_URL": "https://api.mcpshield.xyz"
}
}
}
}
Option 2: With .env File
{
"mcpServers": {
"mcpshield": {
"command": "mcpshield",
"args": ["serve", "--env-file", "/path/to/.env"]
}
}
}
Option 3: With YAML Config
{
"mcpServers": {
"mcpshield": {
"command": "mcpshield",
"args": ["serve", "--config", "/path/to/mcpshield.yaml"],
"env": {
"PG_DSN": "postgresql://user:pass@localhost:5432/db",
"MCPSHIELD_API_KEY": "mcps_...",
"PROJECT_ID": "proj_..."
}
}
}
}
How Policy Synchronization Works
┌──────────────────────────────────────────────────────────────┐
│ MCPShield Dashboard │
│ │
│ 1. Author policy in UI │
│ 2. Save policy (stored in database) │
│ 3. policy_hash computed (SHA-256) │
└──────────────────────────┬───────────────────────────────────┘
│
│ GET /projects/{id}/policy
│
▼
┌────────────────────┐
│ MCPShield Gateway │
│ │
│ On startup: │
│ • Fetch policy │
│ • Cache locally │
│ • Compute hash │
│ │
│ Every 60s: │
│ • Re-fetch policy │
│ • Update cache │
│ • Update hash │
└────────────────────┘
│
│ Every request includes:
│ • decision (allow/deny)
│ • policy_hash
│
▼
┌────────────────────┐
│ Audit Events │
│ │
│ { │
│ decision: allow │
│ policy_hash:... │
│ } │
└────────────────────┘
Configuration
Environment Variables
MCPShield supports configuration via environment variables (no YAML file required):
Required:
DSN,PG_DSN, orDATABASE_URL- Infrastructure connection string (database, API, etc.)MCPSHIELD_BACKEND- Infrastructure type:postgres,mysql,sqlite,mongodb, orredisPROJECT_ID- Your MCPShield project IDMCPSHIELD_API_KEY- Your MCPShield API key
Optional:
API_BASE_URL- API endpoint (default:https://api.mcpshield.xyz)POLICY_SOURCE- Policy source:remote,remote_with_fallback, orlocal(default:remote)POLICY_FILE- Path to local policy file (for fallback)POLICY_REFRESH_SECONDS- Policy refresh interval (default:60)SPOOL_DIR- Event spool directory (default:~/.mcpshield/spool)POLICY_CACHE_DIR- Policy cache directory (default:~/.mcpshield/cache)LOG_LEVEL- Logging level:DEBUG,INFO,WARNING,ERROR(default:INFO)LOG_DECISIONS- Log policy decisions:trueorfalse(default:true)BATCH_SIZE- Event batch size (default:10)BATCH_TIMEOUT- Event batch timeout in seconds (default:5)
Policy Source Options
remote (Recommended - Default):
- Fetches policy from MCPShield API only
- No local policy file needed
- Fails if API unreachable (fail-closed)
- Always uses latest policy from dashboard
- Policy cached locally at
~/.mcpshield/cache/policy.yaml
remote_with_fallback:
- Tries API first
- Falls back to cached policy if API fails
- Falls back to local file if cache unavailable
- Provides resilience during API outages
local:
- Uses local policy file only
- No API calls
- Useful for offline development
- Requires
POLICY_FILEto be set
Fail-Closed Behavior
Gateway WILL NOT start if:
- Policy source is
remoteand API is unreachable (and no cache exists) - Policy source is
remote_with_fallbackand ALL of: API fails, no cache, no local file - This ensures gateway never operates without a policy
Documentation
- User Guide: https://mcpshield.xyz/docs
- Policy Syntax: https://mcpshield.xyz/docs/policy
- Troubleshooting: https://mcpshield.xyz/docs/troubleshooting
Available Tools by Database Type
MCPShield provides consistent tooling across all supported infrastructure types:
PostgreSQL
- postgres_query - Execute SQL queries (SELECT, INSERT, UPDATE, DELETE)
- postgres_describe - List tables, columns, and types
- postgres_dump - Generate SQL DDL backup (CREATE TABLE, indexes, constraints)
- postgres_diagram - Generate Mermaid ER diagrams
MySQL
- mysql_query - Execute SQL queries (SELECT, INSERT, UPDATE, DELETE)
- mysql_describe - List tables, columns, and types
- mysql_dump - Generate SQL DDL backup (CREATE TABLE, indexes, constraints)
- mysql_diagram - Generate Mermaid ER diagrams
SQLite
- sqlite_query - Execute SQL queries (SELECT, INSERT, UPDATE, DELETE)
- sqlite_describe - List tables, columns, and types
- sqlite_dump - Generate SQL DDL backup (CREATE TABLE, indexes, constraints)
- sqlite_diagram - Generate Mermaid ER diagrams
MongoDB
- mongodb_query - Execute find queries on collections
- mongodb_aggregate - Execute aggregation pipelines
- mongodb_describe - List collections and document structure
- mongodb_insert - Insert documents into collections
- mongodb_update - Update documents in collections
- mongodb_delete - Delete documents from collections
- mongodb_dump - Export collections and optionally documents
- mongodb_diagram - Generate Mermaid ER diagrams of collections
Redis
- redis_get - Get value by key
- redis_set - Set key-value pairs with optional TTL
- redis_delete - Delete one or more keys
- redis_keys - List keys matching a pattern (uses SCAN)
- redis_info - Get server info and stats
- redis_describe - Database statistics and key patterns
- redis_backup - Export keys and values matching a pattern
Security
MCPShield is designed with security-first principles:
- Default Deny: All operations blocked unless explicitly allowed
- Read-Only Enforcement: Blocks destructive SQL keywords
- Schema Validation: Only access allowed tables
- Data Redaction: Remove sensitive data (emails, phones) from results
- Rate Limiting: Enforce query limits and timeouts
- Audit Everything: Complete audit trail with policy_hash tracking
CLI Commands
# Run the gateway (env vars only)
mcpshield serve
# Run the gateway (with .env file)
mcpshield serve --env-file .env
# Run the gateway (with YAML config)
mcpshield serve --config mcpshield.yaml
# Validate configuration
mcpshield validate
mcpshield validate --env-file .env
mcpshield validate --config mcpshield.yaml
# Run diagnostics
mcpshield doctor
mcpshield doctor --env-file .env
mcpshield doctor --config mcpshield.yaml
# Get version
mcpshield --version
Support
- Documentation: https://mcpshield.xyz/docs
- Issues: Report via MCPShield support channels
License
MIT License - see LICENSE file for details
Metadata
Release files for mcpshield 0.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcpshield-0.3.3.tar.gz | 49.5 kB | Without provenance | Details for mcpshield-0.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcpshield-0.3.3-py3-none-any.whl | Python 3 | none | any | Details for mcpshield-0.3.3-py3-none-any.whl |
Total release size: 98.6 kB
Release files / mcpshield-0.3.3.tar.gz
| Download URL | mcpshield-0.3.3.tar.gz |
|---|---|
| Size | 49.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
782d6eb9fcd07791bb863156a7f5d00ce45d1470028f4faafef68af69b7e5426
|
|
BLAKE2b-256 checksum How to use checksums |
33d7bc50a0aa4ca36585b56d07ef17b0e1f5b1e5f2f3a639f61f51fad3375db5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
Release files / mcpshield-0.3.3-py3-none-any.whl
| Download URL | mcpshield-0.3.3-py3-none-any.whl |
|---|---|
| Size | 49.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3540cfaea5c8afecbf640f4914d2894645b7c3fea17e717af2e7618cda5ca129
|
|
BLAKE2b-256 checksum How to use checksums |
dce2710ace1160f78000a6a310cd134a1256c39ceaee012f4871706c6a0cd25f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
Security for mcpshield 0.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.