gosecCloud/python-mcp-server

Python MCP Server

A production-grade Model Context Protocol (MCP) server implemented in Python, providing LLM clients like Claude Desktop with secure, performant access to comprehensive developer tooling.

✨ Features

40+ Tools Across 9 Capability Domains

Security-First Design

• Multi-Layer Defense: Workspace confinement, platform-specific sandboxing, policy engine, audit logging
• Approval Workflows: Dry-run previews for destructive operations (write, delete, commit, install)
• Tamper-Evident Audit: Merkle chain for immutable operation tracking
• Platform Sandboxing: Linux namespaces, macOS sandbox-exec, Windows Job Objects

Performance & UX

• Streaming: Real-time progress for long-running operations
• Cancellation: Interrupt any running task via client request
• Caching: Multi-tier (memory + SQLite/LMDB) for files, search index, LSP results
• Incremental Indexing: File watcher triggers targeted re-indexing

Extensibility

• Plugin System: Clean entry points for custom tools
• Per-Plugin Policies: Granular security controls
• Multi-Language: LSP support for Python, TypeScript, and more

🚀 Quick Start

Installation

From Git Repository (Recommended)

# Latest version from main branch
pip install git+https://github.com/gosecCloud/python-mcp-server.git

# Specific version tag
pip install git+https://github.com/gosecCloud/python-mcp-server.git@v0.1.0

# With optional dependencies
pip install "git+https://github.com/gosecCloud/python-mcp-server.git#egg=mcp-python-server[telemetry,fast]"

# Using uv (faster)
uv pip install git+https://github.com/gosecCloud/python-mcp-server.git

For Development

# Clone repository
git clone https://github.com/gosecCloud/python-mcp-server.git
cd python-mcp-server

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Or using uv
uv pip install -e ".[dev]"

Verify Installation

# Check version
python -c "import mcp; print(f'MCP Server v{mcp.__version__}')"

# Check CLI availability
mcp --help
mcp-python-server --help

Configuration

Initialize a project with default configuration:

mcp init

This creates .mcp/config.yaml:

workspace:
  root: "."

commands:
  allow:
    - "pytest"
    - "uv"
    - "poetry"
    - "rg"
  block:
    - "rm"
    - "dd"

git:
  safe_branches:
    - "main"
    - "master"

lsp:
  servers:
    python:
      command: "pylance-langserver"
      args: ["--stdio"]

Running the Server

# STDIO mode (for Claude Desktop)
mcp-python-server --transport stdio --config .mcp/config.yaml

# WebSocket mode (future)
mcp-python-server --transport ws --port 8080

Claude Desktop Integration

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

{
  "mcpServers": {
    "python-mcp": {
      "command": "mcp-python-server",
      "args": ["--transport", "stdio", "--config", "/path/to/project/.mcp/config.yaml"]
    }
  }
}

📖 Documentation

• : Complete system design, layer-by-layer breakdown, security model
• : Project goals, design philosophy, example workflows
• : Roadmap, acceptance criteria, testing strategy
• : Development guide for AI assistants

API Documentation

(Coming soon - Phase 7)

Guides

(Coming soon - Phase 7)

🛠️ Development

Setup

# Clone repository
git clone https://github.com/gosecCloud/python-mcp-server.git
cd python-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=mcp --cov-report=html

# Run specific test file
pytest tests/unit/test_workspace.py

# Run security tests
pytest -m security

Linting & Type Checking

# Lint with ruff
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code
ruff format .

# Type check
mypy src/

🗺️ Roadmap

Current Phase: Phase 0 - Scaffolding (Weeks 1-2)

• Architecture design
• Project structure
• CI/CD setup
• Complete Phase 0 tasks

Upcoming Phases

See for full roadmap.

🤝 Contributing

We welcome contributions! Please see for guidelines.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Areas for Contribution

• Core Features: Implement tools from the roadmap
• Platform Support: Improve sandboxing for Linux/macOS/Windows
• LSP Integration: Add support for new languages
• Testing: Add unit/integration/security tests
• Documentation: Improve guides, examples, API docs
• Plugins: Build community plugins

📊 Project Status

🔒 Security

Security is a first-class concern. Please report vulnerabilities via:

• Email: support@gosec.cloud
• GitHub Security Advisories: Report a vulnerability

See our for details.

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Inspired by the Model Context Protocol
• Built for Claude Desktop and the broader LLM ecosystem
• Thanks to all contributors

📬 Contact

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and discuss
• Email: support@gosec.cloud

Built with ❤️ by GoSec Cloud