# meeseeql
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
- **list_databases** - Lists all configured databases with their types and descriptions
- **search_tables** - Search for tables in the database with optional filtering
- **describe_table** - Gets table structure including columns, data types, and foreign keys
- **execute_query** - Executes SELECT queries on databases with pagination support
- **sample_table** - Samples rows from a table with automatic row limiting
- **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 GitHub
```bash
uvx --from git+https://github.com/txsmith/meeseeql.git meeseeql
```
### For Development
Install dependencies using uv:
```bash
git clone https://github.com/txsmith/meeseeql.git
cd meeseeql
uv sync
```
## 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 meeseeql uvx --from git+https://github.com/txsmith/meeseeql.git meeseeql
```
### Cursor
Add to your MCP settings in Cursor:
1. Open Cursor Settings → Features → Model Context Protocol
2. Add a new server configuration:
```json
{
"meeseeql": {
"command": "uvx",
"args": ["--from", "git+https://github.com/txsmith/meeseeql.git", "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.10",
"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/49/e4/f44790f301cd54bdeb47e503739fa440dea1d21a8fc332cbb02a78ac7012/meeseeql-0.1.0.tar.gz",
"platform": null,
"description": "# meeseeql\nA FastMCP server for exploring multiple databases with support for SELECT queries, table sampling, and structure inspection.\n\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\n- **list_databases** - Lists all configured databases with their types and descriptions\n- **search_tables** - Search for tables in the database with optional filtering\n- **describe_table** - Gets table structure including columns, data types, and foreign keys\n- **execute_query** - Executes SELECT queries on databases with pagination support\n- **sample_table** - Samples rows from a table with automatic row limiting\n- **test_connection** - Tests database connection to verify configuration\n\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\n### From GitHub\n```bash\nuvx --from git+https://github.com/txsmith/meeseeql.git meeseeql\n```\n\n### For Development\nInstall dependencies using uv:\n```bash\ngit clone https://github.com/txsmith/meeseeql.git\ncd meeseeql\nuv sync\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 meeseeql uvx --from git+https://github.com/txsmith/meeseeql.git 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 \"meeseeql\": {\n \"command\": \"uvx\", \n \"args\": [\"--from\", \"git+https://github.com/txsmith/meeseeql.git\", \"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": "0.1.0",
"project_urls": null,
"split_keywords": [
"database",
" fastmcp",
" mcp",
" mysql",
" postgresql",
" sql",
" sqlite"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6e8348a433c95d13aaffa9d7d6cf5c0e1ab50a31d43a679edbf553e80fc4431b",
"md5": "f739d194334dc913b01b820df05dd2fc",
"sha256": "2b7db4f4962e78a931675a08e0cb40d3bbba309c160987d3db3b5affb25ec104"
},
"downloads": -1,
"filename": "meeseeql-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f739d194334dc913b01b820df05dd2fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19604,
"upload_time": "2025-07-26T14:10:30",
"upload_time_iso_8601": "2025-07-26T14:10:30.086986Z",
"url": "https://files.pythonhosted.org/packages/6e/83/48a433c95d13aaffa9d7d6cf5c0e1ab50a31d43a679edbf553e80fc4431b/meeseeql-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "49e4f44790f301cd54bdeb47e503739fa440dea1d21a8fc332cbb02a78ac7012",
"md5": "2a4c5366bda3ed6aceb12c68d13b200d",
"sha256": "fe71950cd8dcbbb3fbb8b5477421cb7dd81c7868ccdd7911e1080bfe25b7b46c"
},
"downloads": -1,
"filename": "meeseeql-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2a4c5366bda3ed6aceb12c68d13b200d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 564195,
"upload_time": "2025-07-26T14:10:31",
"upload_time_iso_8601": "2025-07-26T14:10:31.604760Z",
"url": "https://files.pythonhosted.org/packages/49/e4/f44790f301cd54bdeb47e503739fa440dea1d21a8fc332cbb02a78ac7012/meeseeql-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 14:10:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "meeseeql"
}
JSON