# meeseeql
[](https://github.com/txsmith/meeseeql/actions/workflows/test.yml)
A FastMCP server for exploring multiple databases with support for SELECT queries, table sampling, and structure inspection.
## Features
- **Multiple Database Support**: Configure multiple databases with connection strings or individual fields
- **Safe Query Execution**: Only SELECT queries allowed for read-only exploration
- **Table Sampling**: Sample rows from tables with configurable limits
- **Schema Inspection**: View table structure, columns, and foreign key relationships
> [!WARNING]
> **Use at your own risk**: This tool attempts to restrict database operations to read-only queries (SELECT statements), but it does not guarantee that all destructive operations are prevented. Database functions, stored procedures, or certain SELECT statements with side effects could potentially modify database state. Always use read-only database connections and users with minimal privileges when connecting to production databases.
## Available Tools
- **search** - Search across tables, columns and enum values
- **table_summary** - Gets table structure including columns, data types, and foreign keys
- **execute_query** - Executes SELECT queries on databases with pagination support
- **show_database_config** - Returns the configured DBs + path to the loaded config file
- **reload_config** - Reloads configuration. Allows agents to make changes on-demand
- **test_connection** - Tests database connection to verify configuration
## Supported Databases
- PostgreSQL (via psycopg2)
- MySQL (via PyMySQL)
- SQLite (local files and in-memory)
- SQL Server (via pyodbc)
- Snowflake (data warehouse)
## Installation
From PyPI:
```bash
uvx meeseeql
```
From GitHub:
```bash
uvx --from git+https://github.com/txsmith/meeseeql.git meeseeql
```
For development:
```bash
git clone https://github.com/txsmith/meeseeql.git
cd meeseeql
uv sync --dev
```
## Configuration
Create a `config.yaml` file with your database connections. The config file is searched in this order:
1. `--config /path/to/config.yaml` (command line flag)
2. `MEESEEQL_CONFIG` environment variable
3. `./config.yaml` (current working directory)
4. `~/.config/meeseeql/config.yaml` (recommended for users)
5. `~/meeseeql.yaml` (simple alternative)
See `config_example.yaml` for more examples of both formats.
3. Run the server:
```bash
fastmcp dev main.py
```
## Installing as MCP Server
### Claude Desktop
```bash
claude mcp add --scope user sql-explorer uvx meeseeql
```
### Cursor
Add to your MCP settings in Cursor:
1. Open Cursor Settings → Features → Model Context Protocol
2. Add a new server configuration:
```json
{
"sql-explorer": {
"command": "uvx",
"args": ["meeseeql"]
}
}
```
## Security considerations
Configure your databases with read-only users to prevent destructive operations. The server does not restrict query types at the application level. Also make sure to keep your config.yaml private as this will likely contain sensitive information.
> [!TIP]
> **Password Management**: Instead of storing plaintext passwords in your config file, you can use the Unix [`pass`](https://www.passwordstore.org/) password manager. Simply omit the `password` field from your database configuration and meeseeql will automatically attempt to retrieve the password using `pass databases/{database_name}`. See config_example.yaml for configuration options.
## Development
### Running Tests
```bash
uv run pytest
```
### Code Formatting
```bash
uv run black .
uv run flake8
```
Raw data
{
"_id": null,
"home_page": null,
"name": "meeseeql",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "database, fastmcp, mcp, mysql, postgresql, sql, sqlite",
"author": null,
"author_email": "Thomas Smith <thomas@apolloagriculture.com>",
"download_url": "https://files.pythonhosted.org/packages/0f/17/577a5dd249288b13338966b0158c67b336fb99dcf15bee34b510752e5187/meeseeql-1.1.0.tar.gz",
"platform": null,
"description": "# meeseeql\n[](https://github.com/txsmith/meeseeql/actions/workflows/test.yml)\n\n\nA FastMCP server for exploring multiple databases with support for SELECT queries, table sampling, and structure inspection.\n\n## Features\n\n- **Multiple Database Support**: Configure multiple databases with connection strings or individual fields\n- **Safe Query Execution**: Only SELECT queries allowed for read-only exploration\n- **Table Sampling**: Sample rows from tables with configurable limits\n- **Schema Inspection**: View table structure, columns, and foreign key relationships\n\n\n> [!WARNING]\n> **Use at your own risk**: This tool attempts to restrict database operations to read-only queries (SELECT statements), but it does not guarantee that all destructive operations are prevented. Database functions, stored procedures, or certain SELECT statements with side effects could potentially modify database state. Always use read-only database connections and users with minimal privileges when connecting to production databases. \n\n\n## Available Tools\n- **search** - Search across tables, columns and enum values\n- **table_summary** - Gets table structure including columns, data types, and foreign keys\n- **execute_query** - Executes SELECT queries on databases with pagination support\n- **show_database_config** - Returns the configured DBs + path to the loaded config file\n- **reload_config** - Reloads configuration. Allows agents to make changes on-demand\n- **test_connection** - Tests database connection to verify configuration\n\n## Supported Databases\n\n- PostgreSQL (via psycopg2)\n- MySQL (via PyMySQL)\n- SQLite (local files and in-memory)\n- SQL Server (via pyodbc)\n- Snowflake (data warehouse)\n\n\n## Installation\n\nFrom PyPI:\n```bash\nuvx meeseeql\n```\n\nFrom GitHub:\n```bash\nuvx --from git+https://github.com/txsmith/meeseeql.git meeseeql\n```\n\nFor development:\n```bash\ngit clone https://github.com/txsmith/meeseeql.git\ncd meeseeql\nuv sync --dev\n```\n\n## Configuration\n\nCreate a `config.yaml` file with your database connections. The config file is searched in this order:\n\n1. `--config /path/to/config.yaml` (command line flag)\n2. `MEESEEQL_CONFIG` environment variable\n3. `./config.yaml` (current working directory)\n4. `~/.config/meeseeql/config.yaml` (recommended for users)\n5. `~/meeseeql.yaml` (simple alternative)\n\nSee `config_example.yaml` for more examples of both formats.\n\n3. Run the server:\n```bash\nfastmcp dev main.py\n```\n\n\n## Installing as MCP Server\n\n### Claude Desktop\n```bash\nclaude mcp add --scope user sql-explorer uvx meeseeql\n```\n\n### Cursor\nAdd to your MCP settings in Cursor:\n\n1. Open Cursor Settings \u2192 Features \u2192 Model Context Protocol\n2. Add a new server configuration:\n\n```json\n{\n \"sql-explorer\": {\n \"command\": \"uvx\", \n \"args\": [\"meeseeql\"]\n }\n}\n```\n## Security considerations\nConfigure your databases with read-only users to prevent destructive operations. The server does not restrict query types at the application level. Also make sure to keep your config.yaml private as this will likely contain sensitive information.\n\n> [!TIP]\n> **Password Management**: Instead of storing plaintext passwords in your config file, you can use the Unix [`pass`](https://www.passwordstore.org/) password manager. Simply omit the `password` field from your database configuration and meeseeql will automatically attempt to retrieve the password using `pass databases/{database_name}`. See config_example.yaml for configuration options.\n\n## Development\n\n### Running Tests\n\n```bash\nuv run pytest\n```\n\n### Code Formatting\n\n```bash\nuv run black .\nuv run flake8\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A FastMCP server for exploring SQL databases",
"version": "1.1.0",
"project_urls": null,
"split_keywords": [
"database",
" fastmcp",
" mcp",
" mysql",
" postgresql",
" sql",
" sqlite"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "55e97e0261e45c6f695e96a20855fcd66f0289401a193343cfc680337eedef4c",
"md5": "be7f54ab81663f28f0661e5e44c434b4",
"sha256": "d07fcb25faa43a4203e02321c6d8b6d7a0dc8b4c7bff0ee07444666d9abb7c5d"
},
"downloads": -1,
"filename": "meeseeql-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "be7f54ab81663f28f0661e5e44c434b4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 33479,
"upload_time": "2025-08-06T19:52:28",
"upload_time_iso_8601": "2025-08-06T19:52:28.024069Z",
"url": "https://files.pythonhosted.org/packages/55/e9/7e0261e45c6f695e96a20855fcd66f0289401a193343cfc680337eedef4c/meeseeql-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0f17577a5dd249288b13338966b0158c67b336fb99dcf15bee34b510752e5187",
"md5": "40902b7f965313871b442d939e94053a",
"sha256": "9ef9c7c4501e80299bfa9f94697dc6bfcb9de3b56003cd335a5b0ae277244969"
},
"downloads": -1,
"filename": "meeseeql-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "40902b7f965313871b442d939e94053a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 550089,
"upload_time": "2025-08-06T19:52:29",
"upload_time_iso_8601": "2025-08-06T19:52:29.345580Z",
"url": "https://files.pythonhosted.org/packages/0f/17/577a5dd249288b13338966b0158c67b336fb99dcf15bee34b510752e5187/meeseeql-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-06 19:52:29",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "meeseeql"
}
JSON