KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #open-source #ai #claude-code #codex #developer-tools #react #windows #deepseek-harness #ai-agent

legion-mcp

★ 94 Open GitHub ↗

A server that helps people access and query data in databases using the Legion Query Runner with Model Context Protocol (MCP) in Python.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Multi-Database MCP Server (by Legion AI)

A server that helps people access and query data in databases using the Legion Query Runner with integration of the Model Context Protocol (MCP) Python SDK.

# Start Generation Here
This tool is provided by [Legion AI](https://thelegionai.com/). To use the full-fledged and fully powered AI data analytics tool, please visit the site. Email us if there is one database you want us to support.
# End Generation Here

## Why Choose Database MCP

Database MCP stands out from other database access solutions for several compelling reasons:

- **Unified Multi-Database Interface**: Connect to PostgreSQL, MySQL, SQL Server, and other databases through a single consistent API - no need to learn different client libraries for each database type.
- **AI-Ready Integration**: Built specifically for AI assistant interactions through the Model Context Protocol (MCP), enabling natural language database operations.
- **Zero-Configuration Schema Discovery**: Automatically discovers and exposes database schemas without manual configuration or mapping.
- **Database-Agnostic Tools**: Find tables, explore schemas, and execute queries with the same set of tools regardless of the underlying database technology.
- **Secure Credential Management**: Handles database authentication details securely, separating credentials from application code.
- **Simple Deployment**: Works with modern AI development environments like LangChain, FastAPI, and others with minimal setup.
- **Extensible Design**: Easily add custom tools and prompts to enhance functionality for specific use cases.

Whether you're building AI agents that need database access or simply want a unified interface to multiple databases, Database MCP provides a streamlined solution that dramatically reduces development time and complexity.

## Features

- Multi-database support - connect to multiple databases simultaneously
- Database access via Legion Query Runner
- Model Context Protocol (MCP) support for AI assistants
- Expose database operations as MCP resources, tools, and prompts
- Multiple deployment options (standalone MCP server, FastAPI integration)
- Query execution and result handling
- Flexible configuration via environment variables, command-line arguments, or MCP settings JSON
- User-driven database selection for multi-database setups

## Supported Databases

| Database | DB_TYPE code |
|----------|--------------|
| PostgreSQL | pg |
| Redshift | redshift |
| CockroachDB | cockroach |
| MySQL | mysql |
| RDS MySQL | rds_mysql |
| Microsoft SQL Server | mssql |
| Big Query | bigquery |
| Oracle DB | oracle |
| SQLite | sqlite |

We use Legion Query Runner library as connectors. You can find more info on their [api doc](https://theralabs.github.io/legion-database/docs/category/query-runners).

## What is MCP?

The Model Context Protocol (MCP) is a specification for maintaining context in AI applications. This server uses the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) to:

- Expose database operations as tools for AI assistants
- Provide database schemas and metadata as resources
- Generate useful prompts for database operations
- Enable stateful interactions with databases

## Installation & Configuration

### Required Parameters

For single database configuration:
- **DB_TYPE**: The database type code (see table above)
- **DB_CONFIG**: A JSON configuration string for database connection

For multi-database configuration:
- **DB_CONFIGS**: A JSON array of database configurations, each containing:
  - **db_type**: The database type code
  - **configuration**: Database connection configuration
  - **description**: A human-readable description of the database

The configuration format varies by database type. See the [API documentation](https://theralabs.github.io/legion-database/docs/category/query-runners) for database-specific configuration details.

### Installation Methods

#### Option 1: Using UV (Recommended)

When using [`uv`](https://docs.astral.sh/uv/), no specific installation is needed. We will use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *database-mcp*.

**UV Configuration Example (Single Database):**

```json
REPLACE DB_TYPE and DB_CONFIG with your connection info.
{
    "mcpServers": {
      "database-mcp": {
        "command": "uvx",
        "args": [
          "database-mcp"
        ],
        "env": {
          "DB_TYPE": "pg",
          "DB_CONFIG": "{\"host\":\"localhost\",\"port\":5432,\"user\":\"user\",\"password\":\"pw\",\"dbname\":\"dbname\"}"
        },
        "disabled": true,
        "autoApprove": []
      }
    }
}
```

**UV Configuration Example (Multiple Databases):**

```json
{
    "mcpServers": {
      "database-mcp": {
        "command": "uvx",
        "args": [
          "database-mcp"
        ],
        "env": {
          "DB_CONFIGS": "[{\"id\":\"pg_main\",\"db_type\":\"pg\",\"configuration\":{\"host\":\"localhost\",\"port\":5432,\"user\":\"user\",\"password\":\"pw\",\"dbname\":\"postgres\"},\"description\":\"PostgreSQL Database\"},{\"id\":\"mysql_data\",\"db_type\":\"mysql\",\"configuration\":{\"host\":\"localhost\",\"port\":3306,\"user\":\"root\",\"password\":\"pass\",\"database\":\"mysql\"},\"description\":\"MySQL Database\"}]"
        },
        "disabled": true,
        "autoApprove": []
      }
    }
}
```

#### Option 2: Using PIP

Install via pip:

```bash
pip install database-mcp
```

**PIP Configuration Example (Single Database):**

```json
{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": [
        "-m", "database_mcp", 
        "--repository", "path/to/git/repo"
      ],
      "env": {
        "DB_TYPE": "pg",
        "DB_CONFIG": "{\"host\":\"localhost\",\"port\":5432,\"user\":\"user\",\"password\":\"pw\",\"dbname\":\"dbname\"}"
      }
    }
  }
}
```

## Running the Server

### Production Mode

```bash
python mcp_server.py
```

### Configuration Methods

#### Environment Variables (Single Database)

```bash
export DB_TYPE="pg"  # or mysql, postgresql, etc.
export DB_CONFIG='{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"}'
uv run src/database_mcp/mcp_server.py
```

#### Environment Variables (Multiple Databases)

```bash
export DB_CONFIGS='[{"id":"pg_main","db_type":"pg","configuration":{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"},"description":"PostgreSQL Database"},{"id":"mysql_users","db_type":"mysql","configuration":{"host":"localhost","port":3306,"user":"root","password":"pass","database":"mysql"},"description":"MySQL Database"}]'
uv run src/database_mcp/mcp_server.py
```

If you don't specify an ID, the system will generate one automatically based on the database type and description:

```bash
export DB_CONFIGS='[{"db_type":"pg","configuration":{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"},"description":"PostgreSQL Database"},{"db_type":"mysql","configuration":{"host":"localhost","port":3306,"user":"root","password":"pass","database":"mysql"},"description":"MySQL Database"}]'
# IDs will be generated as something like "pg_postgres_0" and "my_mysqldb_1"
uv run src/database_mcp/mcp_server.py
```

#### Command Line Arguments (Single Database)

```bash
python mcp_server.py --db-type pg --db-config '{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"}'
```

#### Command Line Arguments (Multiple Databases)

```bash
python mcp_server.py --db-configs '[{"id":"pg_main","db_type":"pg","configuration":{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"},"description":"PostgreSQL Database"},{"id":"mysql_users","db_type":"mysql","configuration":{"host":"localhost","port":3306,"user":"root","password":"pass","database":"mysql"},"description":"MySQL Database"}]'
```

Note that you can specify custom IDs for each database using the `id` field, or let the system generate them based on database type and description.

## Multi-Database Support

When connecting to multiple databases, you need to specify which database to use for each query:

1. Use the `list_databases` tool to see available databases with their IDs
2. Use `get_database_info` to view schema details of databases
3. Use `find_table` to locate a table across all databases
4. Provide the `db_id` parameter to tools like `execute_query`, `get_table_columns`, etc.

Database connections are managed internally as a dictionary of `DbConfig` objects, with each database having a unique ID. Schema information is represented as a list of table objects, where each table contains its name and column information.

The `select_database` prompt guides users through the database selection process.

## Schema Representation

Database schemas are represented as a list of table objects, with each table containing information about its columns:

```json
[
  {
    "name": "users",
    "columns": [
      {"name": "id", "type": "integer"},
      {"name": "username", "type": "varchar"},
      {"name": "email", "type": "varchar"}
    ]
  },
  {
    "name": "orders",
    "columns": [
      {"name": "id", "type": "integer"},
      {"name": "user_id", "type": "integer"},
      {"name": "product_id", "type": "integer"},
      {"name": "quantity", "type": "integer"}
    ]
  }
]
```

This representation makes it easy to programmatically access table and column information while keeping a clean hierarchical structure.

## Exposed MCP Capabilities

### Resources

| Resource | Description |
|----------|-------------|
| `resource://schema/{database_id}` | Get the schemas for one or all configured databases |

### Tools

| Tool | Description |
|------|-------------|
| `execute_query` | Execute a SQL query and return results as a markdown table |
| `execute_query_json` | Execute a SQL query and return results as JSON |
| `get_table_columns` | Get column names for a specific table |
| `get_table_types` | Get column types for a specific table |
| `get_query_history` | Get the recent query history |
| `list_databases` | List all available database connections |
| `get_database_info` | Get detailed information about a database including schema |
| `find_table` | Find which database contains a specific table |
| `describe_table` | Get detailed description of a table including column names and types |
| `get_table_sample` | Get a sample of data from a table |

All database-specific tools (like `execute_query`, `get_table_columns`, etc.) require a `db_id` parameter to specify which database to use.

### Prompts

| Prompt | Description |
|--------|-------------|
| `sql_query` | Create an SQL query against the database |
| `explain_query` | Explain what a SQL query does |
| `optimize_query` | Optimize a SQL query for better performance |
| `select_database` | Help user select which database to use |

## Development

### Using MCP Inspector

run this to start the inspector
```bash
npx @modelcontextprotocol/inspector uv run src/database_mcp/mcp_server.py
```

then in the command input field, set something like
```
run src/database_mcp/mcp_server.py --db-type pg --db-config '{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"}'
```

### Testing

```bash
uv pip install -e ".[dev]"
pytest
```

### Publishing

```bash
# Clean up build artifacts
rm -rf dist/ build/ 
# Remove any .egg-info directories if they exist
find . -name "*.egg-info" -type d -exec rm -rf {} + 2>/dev/null || true
# Build the package
uv run python -m build
# Upload to PyPI
uv run python -m twine upload dist/*
```

## License

This repository is licensed under GPL

legion-mcp

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README