Provides safe, read-only querying and schema inspection of PostgreSQL databases with AST-based validation, table allow-listing, enforced row limits, and statement timeouts.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Lens-MCP List available tables"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Lens-MCP is a read-only Postgres MCP server that lets AI agents inspect and query approved database data safely.
The point is not to expose SQL over MCP. That is easy and dangerous. The point is to put a deliberate safety layer between the agent and Postgres: AST-based SQL validation, table allow-listing, enforced row limits, query timeouts, and a read-only database user.
Lens-MCP provides four MCP tools:
list_tables
describe_table(table_name)
sample_table(table_name, limit)
query(sql)
The MVP uses stdio transport because it is the right default for local MCP clients such as Claude Desktop and Cursor. HTTP transport, hosted deployments, dashboards, and orchestration are intentionally out of scope until the local safety model is proven.
Related MCP server: postgres-mcp-query-tool
Lens-MCP uses defense in depth:
Only single-statement SELECT queries are accepted.
SQL is parsed with sqlglot; security does not rely on substring checks.
Every referenced table must be present in LENS_ALLOWED_TABLES.
Missing limits receive LENS_DEFAULT_ROW_LIMIT.
Excessive limits are capped by LENS_MAX_ROW_LIMIT.
Every database call applies LENS_STATEMENT_TIMEOUT_MS.
The database connection should use a Postgres role with SELECT privileges only.
This does not make arbitrary databases safe by itself. It reduces the blast radius, but the Postgres role must still be read-only and the allow-list must exclude sensitive tables.
Create a virtual environment and install the package:
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"Start the demo database:
docker compose -f infra/docker-compose.yml up -dExport local settings:
export LENS_DATABASE_URL="postgresql://lens_readonly:lens_readonly@localhost:5432/lens_demo"
export LENS_ALLOWED_TABLES="public.customers,public.orders"
export LENS_DEFAULT_ROW_LIMIT="100"
export LENS_MAX_ROW_LIMIT="500"
export LENS_STATEMENT_TIMEOUT_MS="5000"
export LENS_SCHEMA_NAME="public"Run the MCP server:
lens-mcpUse examples/claude_desktop_config.json as the starting point for local client configuration.
Useful smoke-test prompts:
List the tables available through Lens-MCP.
Describe the customers table.
Show two sample rows from orders.
Run SELECT * FROM public.customers and tell me what limit was applied.
Try to delete from public.customers and explain why the tool refused.
Variable | Purpose | Default |
| Postgres connection URL | empty |
| Comma-separated allow-list such as | empty |
| Limit added when a query has no limit |
|
| Maximum allowed limit |
|
| Postgres statement timeout |
|
| Schema used by introspection and table samples |
|
Safe defaults are restrictive. If LENS_ALLOWED_TABLES is empty, database tables are not exposed.
ruff check .
mypy src tests
pytestRun the optional live Postgres integration tests after starting Docker Compose:
LENS_INTEGRATION_DATABASE_URL="postgresql://lens_readonly:lens_readonly@localhost:5432/lens_demo" pytest tests/test_integration_postgres.pyKubernetes, Terraform, service mesh, queues, and dashboards are not signs of professionalism for this project. Lens-MCP is a small stateless adapter over Postgres. The professional signal is a clean boundary between MCP protocol, security validation, data access, configuration, and tests that prove unsafe SQL cannot slip through.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| table_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0describe_tablelist_tablesquerysample_tableEach tool has a distinct, clearly separate purpose: listing tables, describing schema, running queries, and sampling data. No overlap.
Three tools follow 'verb_noun' pattern consistently; 'query' deviates slightly as a single verb, but this is acceptable for a common database command.
Four tools is well-scoped for a database exploration server, covering core operations without excess.
The set covers essential data exploration operations (list, describe, sample, query). Missing write or administrative tools, but that fits the exploration focus.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Xata MCP server lets AI agents interact with your Xata projects, and Postgres database branches.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Hqzdev/Lens-MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
