secure MCP server
Commit Nov 5, 2026Provides a security-hardened MCP interface for Kali Linux using OAuth 2.0, TLS, and strict tool allowlisting to prevent arbitrary command execution.
Also known as Zer-project/secure-mcp-server
- Stars
- 2
- Tools
- 7
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 5, 2026
- License
- Apache-2.0
What is secure MCP?
secure provides a security-hardened MCP interface for Kali Linux using OAuth 2.0, TLS, and strict tool allowlisting to prevent arbitrary command execution. It exposes 7 tools, such as kali_info, system_status, disk_status.
Summary generated from the project's README
About secure MCP server
Providing a hardened interface for Kali Linux is what this server enables for developers who need to grant AI clients access to system information without risking arbitrary command execution. It operates on trusted local networks using HTTPS with a minimum of TLS 1.2 and ECDSA P-256 certificates. Instead of a generic shell, it uses a strict allowlist of read-only tools that can be accessed via an MCP client over a local network.
Security is managed through OAuth 2.0 with PKCE and a single mcp:read scope. The server includes rate limiting on key endpoints, DNS rebinding protection, and audit logging that redacts sensitive arguments like passwords or tokens. Users must configure environment variables such as MCP_PUBLIC_HOST and MCP_PORT to establish the connection. Because it lacks a shell and restricts file access to a specific workspace, it minimizes the potential damage from prompt injection or leaked credentials.
Written from the project's README. Every use case is checked against a quote from it.
secure MCP tools 7
Detected from the READMEkali_infosystem_statusdisk_statusmemory_statusnetwork_statusnetwork_interfacesread_text_file
| kali_info | — | |
| system_status | — | |
| disk_status | — | |
| memory_status | — | |
| network_status | — | |
| network_interfaces | — | |
| read_text_file | — |
Configuration
MCP_PORTMCP_PUBLIC_HOST
| Name | Description | |
|---|---|---|
| MCP_PORT | — | |
| MCP_PUBLIC_HOST | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablezer-project/secure-mcp-server is public and reachablegithub.com/zer-project/secure-mcp-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-05github.com/zer-project/secure-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model7 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubsecure-mcp-server
An MCP server for Kali Linux that deliberately has no shell access.
Read-only, allowlisted tools behind OAuth 2.0 + PKCE, TLS, rate limiting, and audit logging.
[!WARNING] This project is designed for trusted local networks. Public internet exposure is not a supported deployment scenario. Review the Threat Model and Limitations before deployment.
Current release: v1.0.0
Documentation
- Why this project exists
- Features
- Architecture
- Available Tools
- Security Model
- Threat Model and Limitations
- Configuration Reference
- Quick Start
- Testing
- Project Structure
- Development Principles
- Roadmap
- Responsible Use
- Security Policy
- License
Why this project exists
Many MCP servers give an AI client a generic shell or exec endpoint. That makes a single prompt-injection or a leaked token potentially equivalent to broad control of the host.
secure-mcp-server takes the opposite approach: the client can only call a small set of explicitly registered, read-oriented tools. There is no shell, no command execution endpoint, and no arbitrary code execution interface.
Access is authenticated with OAuth 2.0 + PKCE and scoped to mcp:read.
Features
- OAuth 2.0 Authorization Code and Refresh Token flows with PKCE (S256)
- Single MCP scope:
mcp:read - Dynamic public-client registration
- Token revocation
- SQLite-backed OAuth state
- Interactive consent step
- JWT signing with EdDSA (Ed25519)
- HTTPS with minimum TLS 1.2
- ECDSA P-256 certificate generation and validation
- DNS rebinding protection and explicit host allowlisting
- Rate limiting on
/register,/authorize,/token,/revoke, and/mcp - Audit logging with recursive redaction of sensitive arguments
- Refuses to run as root
- Read-only, explicitly registered MCP tools
- Test coverage for OAuth, transport security, TLS, rate limiting, validation, and tools
Architecture
MCP Client (e.g. Termux)
|
| HTTPS + OAuth 2.0 + PKCE
v
Kali Linux MCP Server
|
+-- Streamable HTTP
+-- Host validation
+-- Rate limiting
+-- OAuth authorization
+-- Audit logging
|
v
Allowlisted read-only MCP tools
The client connects over the local network to:
https://<MCP_PUBLIC_HOST>:<MCP_PORT>/mcp
Available Tools
| Tool | Purpose |
|---|---|
kali_info |
Returns Kali/server information |
system_status |
Reports general system status |
disk_status |
Reports disk/storage information |
memory_status |
Reports memory information |
network_status |
Reports network status |
network_interfaces |
Lists network interface information |
read_text_file |
Reads permitted text-file content |
read_text_file restrictions
read_text_file is deliberately restricted:
- Files must remain within the project workspace.
- Absolute paths are rejected.
- Path traversal is rejected.
- Symlink escapes outside the permitted workspace are rejected.
- Maximum readable file size is 1 MiB.
New capabilities should be added as dedicated tools. Do not add generic command execution.
Security Model
Authentication and authorization
- OAuth 2.0 Authorization Code flow
- Refresh Token flow
- Public-client registration
- PKCE with S256
- Single supported MCP scope:
mcp:read - Resource validation
- Short-lived authorization requests and authorization codes
- Authorization codes are single-use
- Refresh tokens are stored hashed
- Token revocation is enabled
- Dynamic registration is limited to the supported scope
PKCE
PKCE protects the authorization-code exchange for the public-client model used by this project.
The integration test verifies the S256 flow, including rejection of an incorrect code verifier.
Token lifetimes
| Item | Default |
|---|---|
| Authorization request | 300 s |
| Authorization code | 300 s |
| Access token | 900 s (15 min) |
| Refresh token | 2,592,000 s (30 days) |
Transport security
- HTTPS only
- Minimum TLS 1.2
- Restricted ECDSA cipher suites
- DNS rebinding protection
- Explicit host allowlisting
- ECDSA P-256 certificates
- Certificate SAN validation
- Certificate/private-key matching checks
Rate limiting
Rate limiting is applied to:
/register
/authorize
/token
/revoke
/mcp
Default:
10 requests / 60 seconds
Both values are configurable.
Audit logging
Audit records are written to:
logs/audit.log
Records include:
- Timestamp
- Tool name
- Sanitized arguments
- Execution status
- Result or error information
Sensitive keys are recursively redacted, including:
api_keyauthorizationclient_secretpasswordrefresh_tokensecrettoken
The sanitizer handles nested dictionaries and sequences without modifying the original input.
Threat Model and Limitations
This project reduces the blast radius of giving an AI client access to a Kali host. It does not make the host safe to expose to the public internet.
Designed to protect against
- Arbitrary command execution through the MCP interface
- Unauthenticated access to protected tools
- Authorization-code interception risks addressed by PKCE
- DNS rebinding against the local server
- Brute-force and flooding of protected endpoints through rate limiting
- Sensitive values leaking into audit logs
Not covered / known limitations
- Intended for use on a trusted local network
- Public internet exposure is not a supported deployment scenario
- The project has not been independently audited
- Dynamic client registration is available to clients that can reach the server; authorization still requires the configured consent flow
- The default certificate is self-signed
- Anything an authorized read-oriented tool can return can be viewed by the authorized client
- The rate limiter is process-local and does not provide distributed/shared rate-limit state
Review every tool before adding it to the allowlist.
Configuration Reference
Configuration is controlled through environment variables defined in config.py.
| Variable | Default | Description |
|---|---|---|
MCP_HOST |
0.0.0.0 |
Bind address |
MCP_PORT |
8000 |
Listening port |
MCP_PUBLIC_HOST |
192.168.1.7 |
Address clients use; change for your network |
MCP_ISSUER |
https://<MCP_PUBLIC_HOST>:<MCP_PORT> |
OAuth issuer URL |
MCP_RESOURCE |
<MCP_ISSUER>/mcp |
Protected resource URL |
JWT_ALGORITHM |
EdDSA |
JWT signing algorithm |
MCP_PUBLIC_KEY_PATH |
secrets/jwt-ed25519-public.pem |
JWT public key |
MCP_PRIVATE_KEY_PATH |
secrets/jwt-ed25519-private.pem |
JWT private key |
OAUTH_DB_PATH |
data/oauth.db |
SQLite OAuth database |
MCP_TLS_CERT_PATH |
secrets/tls/mcp-server.crt |
TLS certificate |
MCP_TLS_KEY_PATH |
secrets/tls/mcp-server.key |
TLS private key |
AUTHORIZATION_REQUEST_TTL_SECONDS |
300 |
Authorization request lifetime |
AUTHORIZATION_CODE_TTL_SECONDS |
300 |
Authorization code lifetime |
ACCESS_TOKEN_TTL_SECONDS |
900 |
Access token lifetime |
REFRESH_TOKEN_TTL_SECONDS |
2592000 |
Refresh token lifetime |
OAUTH_RATE_LIMIT |
10 |
Requests allowed per window |
OAUTH_RATE_LIMIT_WINDOW_SECONDS |
60 |
Rate-limit window |
Keep private keys, OAuth state, and audit logs out of version control.
Quick Start
Prerequisites
- Kali Linux or another Linux host with Python 3 and
openssl - A non-root user
- A client that supports MCP over Streamable HTTP with OAuth
1. Install
git clone https://github.com/Zer-security/secure-mcp-server.git
cd secure-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
mkdir -p logs data secrets/tls
2. Generate JWT signing keys
openssl genpkey -algorithm ED25519 -out secrets/jwt-ed25519-private.pem
openssl pkey -in secrets/jwt-ed25519-private.pem -pubout -out secrets/jwt-ed25519-public.pem
chmod 600 secrets/jwt-ed25519-private.pem
3. Generate the TLS certificate
PYTHONPATH=. python scripts/generate_tls.py
The generated certificate uses ECDSA P-256. Certificate handling includes certificate/key compatibility checks, SAN validation, backup, and rollback on promotion failure.
The default certificate is self-signed, so an MCP client must be configured to trust it.
4. Configure
Set the server's LAN address:
export MCP_PUBLIC_HOST=192.168.x.x
export MCP_PORT=8000
The server uses explicit host validation based on the configured public host and port.
5. Run
PYTHONPATH=. python server.py
The MCP endpoint is:
https://<MCP_PUBLIC_HOST>:8000/mcp
The server refuses to run as root.
6. Connect a client
Point an MCP-compatible client at the MCP endpoint.
The authorization flow uses dynamic public-client registration, an interactive consent step, OAuth 2.0 Authorization Code flow, and PKCE S256.
Testing
The release v1.0.0 was verified with:
124 passed
Historical full-suite command used for v1.0.0:
PYTHONPATH=. ./venv/bin/pytest -q
Current CI command:
PYTHONPATH=. pytest -q --ignore=tests/test_integration.py
Current CI verification: 123 passed.
The suite covers:
- OAuth provider and integration flow
- Authentication
- Transport security
- TLS
- Rate limiting
- SSRF/network security
- Input validation
- File tools
- MCP tools
- Audit logging and sanitization
- Configuration
The release commit is:
f642badaa27315e6b446e1b4370cf113fdc652e1
Project Structure
secure-mcp-server/
├── core/
│ ├── audit_extension.py
│ ├── audit_sanitizer.py
│ ├── oauth_provider.py
│ ├── oauth_routes.py
│ ├── rate_limit.py
│ ├── security.py
│ ├── ssrf.py
│ └── validation.py
├── scripts/
│ └── generate_tls.py
├── tools/
│ ├── file_tools.py
│ ├── info_tools.py
│ ├── network_tools.py
│ └── system_tools.py
├── tests/
├── config.py
├── server.py
├── test_client.py
├── requirements.txt
├── LICENSE
└── README.md
Development Principles
- Least privilege and explicit allowlisting
- Secure defaults
- No generic shell or command execution
- No hardcoded secrets
- Input validation
- Authentication before protected operations
- Auditability
- Fail-safe behavior
- Reproducible testing
- Evidence-based security claims
Workflow:
Implement
↓
Test
↓
Verify
↓
Document
A feature should not be described as secure merely because it exists in source code. The implementation and relevant tests should be verified first.
Roadmap
- GitHub Actions CI with automated tests
- Dependency/update automation
- Additional read-only tools reviewed against the least-privilege model
- Documented MCP client setup guides
- Additional security hardening based on verified requirements
Responsible Use
Use this software only on systems you own or are explicitly authorized to administer or test.
The project is intended for controlled, authorized environments and should not be treated as a general-purpose remote administration interface.
Security Policy
If you discover a security vulnerability, avoid publishing sensitive details in a public issue.
Use the repository's GitHub Security Advisory mechanism for private vulnerability reporting.
License
Licensed under the Apache License 2.0.
secure MCP questions
What tools does secure MCP provide?
It exposes 7 tools, including kali_info, system_status, disk_status, memory_status, network_status.
Can I run arbitrary commands through this server?
No, the server is designed with no shell access and no command execution endpoints; it only allows a small set of explicitly registered, read-oriented tools.
Is it safe to expose this server to the public internet?
No, the project is designed for trusted local networks and public internet exposure is not a supported deployment scenario.
What authentication methods are used?
The server uses OAuth 2.0 Authorization Code and Refresh Token flows with PKCE (S256).
Are there restrictions on reading files?
Yes, files must stay within the project workspace, absolute paths and path traversals are rejected, and the maximum file size is 1 MiB.