A Python collection of MCP (Model Context Protocol) tools — a testing client and production MCP servers, distributed as a single package with optional extras.

# Core only
pip install mamba-mcp
# With specific servers
pip install mamba-mcp[pg] # PostgreSQL server
pip install mamba-mcp[fs] # Filesystem server (local + S3)
pip install mamba-mcp[hana] # SAP HANA server
pip install mamba-mcp[gitlab] # GitLab server
# Client (TUI, CLI, Python API)
pip install mamba-mcp[client]
# Everything
pip install mamba-mcp[all]

Testing and debugging tool for MCP servers. Supports stdio, SSE, HTTP, and UV-based transports.

Mamba MCP Client

• Interactive TUI — Textual-based terminal interface for exploring servers in real-time
• CLI Commands — Quick one-off commands for inspection and scripting
• Python API — Fully async programmatic interface for test automation
• Protocol Logging — Detailed request/response capture with timing

# Launch interactive TUI
mamba-mcp tui --stdio "python server.py"
# CLI inspection
mamba-mcp tools --stdio "python server.py"
mamba-mcp call add --args '{"a": 5, "b": 3}' --stdio "python server.py"

PostgreSQL MCP server with a 3-layer tool architecture for AI assistants.

• Layer 1: Schema Discovery — List schemas, tables, describe columns, sample rows
• Layer 2: Relationship Discovery — Foreign keys, join path finding (BFS)
• Layer 3: Query Execution — Read-only SQL with parameterized queries and EXPLAIN support

# Test database connection
mamba-mcp-pg --env-file mamba.env test
# Run the MCP server
mamba-mcp-pg --env-file mamba.env

Filesystem MCP server with local and S3 backends for AI assistants.

• Layer 1: Discovery — List directories, read files, get metadata, search by name/content
• Layer 2: S3 Extras — List buckets, presigned URLs, object metadata (when S3 enabled)
• Layer 3: Mutation — Write, delete, move, copy files, create directories (when read-write)

# Test configuration and backend connectivity
mamba-mcp-fs --env-file mamba.env test
# Run the MCP server
mamba-mcp-fs --env-file mamba.env

SAP HANA MCP server with a 4-layer tool architecture for AI assistants.

• Layer 1: Schema Discovery — List schemas, tables, describe columns, sample rows
• Layer 2: Relationship Discovery — Foreign keys, join path finding (BFS)
• Layer 3: Query Execution — Read-only SQL with parameterized queries and EXPLAIN support
• HANA-Specific Tools — Calculation views, column/row store type, stored procedures

# Test database connection
mamba-mcp-hana --env-file mamba.env test
# Run the MCP server
mamba-mcp-hana --env-file mamba.env

GitLab MCP server for merge requests, issues, pipelines, and search.

• Merge Requests (7) — List, get, diffs, commits, pipelines, create, update
• Issues (6) — List, get, comments, create, update, add comment
• Pipelines (4) — List, get, jobs, job log
• Search (1) — Instance, project, or group scoped search

# Test GitLab connectivity
mamba-mcp-gitlab --env-file mamba.env test
# Run the MCP server
mamba-mcp-gitlab --env-file mamba.env

All four MCP server modules follow a consistent internal architecture built on FastMCP with a layered tool system:

__main__.py (Typer CLI)
 → server.py (FastMCP + lifespan resource management)
 → tools/ (MCP tool handlers, organized by layer)
 → database/ or backends/ (service layer)
 → models/ (Pydantic I/O contracts)

Shared patterns across servers:

• Layered Tools — Tools progress from discovery → relationships → execution, designed for incremental exploration by AI agents
• AppContext via Lifespan — Resources (DB engines, connection pools, backends) initialized at startup, cleaned up on shutdown
• Pydantic Settings — Environment-based configuration with MAMBA_MCP_{PKG}_* prefix and mamba.env file auto-discovery
• Error Framework — Structured error codes with fuzzy name matching ("did you mean?") suggestions
• Service Layer — Thin tool handlers delegate to service classes that encapsulate domain logic

Tech stack: Python 3.11+, FastMCP, Pydantic, Typer, Textual, SQLAlchemy+asyncpg, hdbcli, fsspec+s3fs, httpx

All servers use mamba.env for environment-based configuration. Default file locations (checked in order):

1. ./mamba.env (project-local)
2. ~/mamba.env (global fallback)

# Install with all extras and dev tools
uv sync --all-extras --group dev
# Run tests
uv run pytest tests/ # all tests
uv run pytest tests/pg/ # per-module
uv run pytest tests/core/ tests/client/ # multiple modules
# Type check
uv run mypy src/
# Lint and format
uv run ruff check src/
uv run ruff format src/

mamba-mcp/
├── pyproject.toml # Single package config with extras
├── uv.lock # Shared lockfile
├── src/
│ ├── mamba_mcp_core/ # Shared utilities
│ ├── mamba_mcp_client/ # MCP testing client
│ ├── mamba_mcp_pg/ # PostgreSQL MCP server
│ ├── mamba_mcp_fs/ # Filesystem MCP server
│ ├── mamba_mcp_hana/ # SAP HANA MCP server
│ └── mamba_mcp_gitlab/ # GitLab MCP server
├── tests/
│ ├── core/
│ ├── client/
│ ├── pg/
│ ├── fs/
│ ├── hana/
│ └── gitlab/
├── examples/ # Client usage examples
├── docs/ # MkDocs documentation
└── internal/ # Specs & images

MIT