image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] image:https://img.shields.io/badge/Philosophy-Palimpsest-purple.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-licence"]

// SPDX-License-Identifier: MIT // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell

= Polyglot DB MCP :toc: macro :toclevels: 2 :icons: font :source-highlighter: rouge

One MCP server. 20 databases. Zero context switching.

Query PostgreSQL, MongoDB, Neo4j, Elasticsearch, Redis, and 15 more databases through a single unified interface. Built with ReScript, runs on Deno.

image:https://img.shields.io/badge/Runtime-Deno-black.svg[Runtime: Deno,link=https://deno.land] image:https://img.shields.io/badge/Language-ReScript-red.svg[Language: ReScript,link=https://rescript-lang.org]

toc::[]

== Why Polyglot DB?

Modern applications use multiple databases — SQL for transactions, Redis for caching, Elasticsearch for search, vectors for AI. Switching between CLIs, APIs, and query languages is exhausting.

Polyglot DB MCP gives Claude (and other MCP clients) direct access to all your databases through natural language:

[quote] Find all users in PostgreSQL who signed up last week, then check if they're in the Redis cache

[quote] Search Elasticsearch for 'authentication errors' and correlate with the MongoDB audit log

[quote] Store this embedding in Qdrant and link it to the Neo4j knowledge graph

== Installation

=== Option A: Direct (Recommended for development)

[source,bash]

Clone the repository

git clone https://github.com/hyperpolymath/polyglot-db-mcp.git cd polyglot-db-mcp

Add to Claude Code

claude mcp add polyglot-db -- deno run
--allow-net --allow-read --allow-write --allow-env
$(pwd)/server.js

=== Option B: Container (Recommended for production)

[source,bash]

Using nerdctl (containerd)

nerdctl run -d --name polyglot-db
-e POSTGRES_HOST=host.docker.internal
-e MONGODB_URL=mongodb://host.docker.internal:27017
ghcr.io/hyperpolymath/polyglot-db-mcp:latest

Using podman

podman run -d --name polyglot-db
-e POSTGRES_HOST=host.containers.internal
ghcr.io/hyperpolymath/polyglot-db-mcp:latest

Using docker

docker run -d --name polyglot-db
-e POSTGRES_HOST=host.docker.internal
ghcr.io/hyperpolymath/polyglot-db-mcp:latest

=== Option C: Deno Deploy (Serverless / HTTP Mode)

Polyglot DB MCP supports the MCP Streamable HTTP transport (June 2025 spec) for cloud deployment:

[source,bash]

Deploy to Deno Deploy

deployctl deploy --project=polyglot-db-mcp server.js

Or run HTTP mode locally

deno task serve

Once deployed, configure your MCP client to connect via HTTP:

[source,json]

{ "mcpServers": { "polyglot-db": { "transport": { "type": "http", "url": "https://polyglot-db-mcp.deno.dev/mcp" } } } }

HTTP endpoints:

• GET /health - Health check
• GET /info - Server information
• POST /mcp - MCP Streamable HTTP endpoint (JSON-RPC 2.0)

== Quick Start

=== 1. Configure your databases

Create a .env file or export environment variables:

[source,bash]

Example: PostgreSQL + Redis + Elasticsearch

export POSTGRES_HOST=localhost POSTGRES_DATABASE=myapp export DRAGONFLY_HOST=localhost export ELASTICSEARCH_URL=http://localhost:9200

=== 2. Ask Claude

"What databases are connected?" "Show me the schema of the users table in PostgreSQL" "Cache this result in Redis with a 1 hour TTL"

== Runtime Modes

This MCP server supports both deployment modes:

|=== |Mode |Supported |Permissions |Notes

|Local-Agent (stdio) |✓ Yes |--allow-net --allow-read --allow-write --allow-env |Primary mode. Direct database connections.

|Hosted-HTTP |✓ Yes |N/A (HTTP transport) |Deploy to Deno Deploy or any HTTP host. |===

=== Local-Agent Mode

[source,bash]

deno run --allow-net --allow-read --allow-write --allow-env server.js

=== Hosted-HTTP Mode

[source,bash]

Deploy to Deno Deploy

deployctl deploy --project=polyglot-db-mcp server.js

Or run locally with HTTP

deno task serve

== Security Boundary

[NOTE]

Unlike CLI-wrapping MCPs, Polyglot DB MCP uses direct database drivers via npm packages. There is no shell execution (--allow-run is not required).

What this means:

• Database credentials are passed via environment variables
• Connections are made directly from the MCP server to databases
• No external CLI tools are executed
• The security boundary is your database authentication

Recommendations:

1. Use database users with minimal necessary permissions
2. Consider read-only users for exploration/query tools
3. Avoid superuser/admin credentials
4. Use connection encryption (SSL/TLS) where available
5. Set network ACLs on database servers
6. Review tool calls before approving in your MCP client

== Smoke Test

Verify the server is working correctly:

[source,bash]

1. Set at least one database connection

export POSTGRES_HOST=localhost POSTGRES_DATABASE=postgres

2. Start the server

deno run --allow-net --allow-read --allow-write --allow-env server.js & SERVER_PID=$!

3. The MCP client should be able to call:

- db_list (lists all supported databases)

- db_status (shows connected databases)

- pg_query "SELECT 1" (if PostgreSQL configured)

4. Cleanup

kill $SERVER_PID

Expected smoke test results:

|=== |Check |Expected Result

|Server starts |No errors, listens on stdio (or HTTP port)

|db_list works |Returns list of 20 supported databases

|db_status works |Shows which databases have valid connections

|pg_query (if PostgreSQL) |Returns query results |===

== Supported Databases

=== Relational

[cols="1,1,2,1",options="header"] |=== |Database |License |Best For |Tools

|PostgreSQL |PostgreSQL (FOSS) |Complex queries, ACID, extensions (PostGIS, pgvector) |pg_* |MariaDB |GPL v2 (FOSS) |Web apps, MySQL compatibility |maria_* |SQLite |Public Domain |Local storage, embedded, single-file |sqlite_* |===

=== Document

[cols="1,1,2,1",options="header"] |=== |Database |License |Best For |Tools

|MongoDB |SSPL |Flexible schemas, horizontal scaling |mongo_* |SurrealDB |BSL/Apache 2.0 |Multi-model (doc + graph + SQL) |surreal_* |ArangoDB |Apache 2.0 (FOSS) |Multi-model (doc + graph + KV), AQL |arango_* |CouchDB |Apache 2.0 (FOSS) |Document DB with HTTP API, Mango queries |couchdb_* |===

=== Wide Column

[cols="1,1,2,1",options="header"] |=== |Database |License |Best For |Tools

|Cassandra |Apache 2.0 (FOSS) |Distributed, high availability, time-series |cassandra_* |===

=== Graph

[cols="1,1,2,1",options="header"] |=== |Database |License |Best For |Tools

|Neo4j |GPL v3 / Commercial |Relationships, social networks, fraud detection |neo4j_* |Virtuoso |GPL v2 / Commercial |RDF triplestore, SPARQL, linked data |virtuoso_* |===

=== Cache & Key-Value

[cols="1,1,2,1",options="header"] |=== |Database |License |Best For |Tools

|Dragonfly |BSL |Redis replacement, 25x faster |dragonfly_* |Memcached |BSD (FOSS) |Simple distributed caching |memcached_* |LMDB |OpenLDAP (FOSS) |Embedded KV with ACID |lmdb_* |===

=== Search

[cols="1,1,2,1",options="header"] |=== |Database |License |Best For |Tools

|Elasticsearch |Elastic License 2.0 |Full-text search, log analytics |es_* |Meilisearch |MIT (FOSS) |Instant, typo-tolerant search |meili_* |===

=== Vector

[cols="1,1,2,1",options="header"] |=== |Database |License |Best For |Tools

|Qdrant |Apache 2.0 (FOSS) |AI embeddings, semantic search |qdrant_* |===

=== Time Series

[cols="1,1,2,1",options="header"] |=== |Database |License |Best For |Tools

|InfluxDB |MIT (v1) |IoT, monitoring, metrics |influx_* |===

=== Analytics

[cols="1,1,2,1",options="header"] |=== |Database |License |Best For |Tools

|DuckDB |MIT (FOSS) |OLAP, query CSV/Parquet/JSON directly |duck_* |===

=== Specialized

[cols="1,1,2,1",options="header"] |=== |Database |License |Best For |Tools

|XTDB |MIT (FOSS) |Bitemporal queries, audit trails |xtdb_* |iTop |AGPL v3 (FOSS) |IT asset management, CMDB |itop_* |===

NOTE: FOSS = Free & Open Source | Source-Available = viewable but restricted

== Configuration

Each database reads from environment variables. Only configure what you need.

=== PostgreSQL

[source,bash]

POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DATABASE=mydb POSTGRES_USER=postgres POSTGRES_PASSWORD=secret

Connection pool (optional)

POSTGRES_POOL_MAX=10 # Max connections POSTGRES_IDLE_TIMEOUT=30 # Seconds before idle connection closed POSTGRES_CONNECT_TIMEOUT=10 # Connection timeout in seconds

=== MongoDB

[source,bash]

MONGODB_URL=mongodb://localhost:27017 MONGODB_DATABASE=mydb

Connection pool (optional)

MONGODB_POOL_MAX=10 # Max connections MONGODB_POOL_MIN=1 # Min connections MONGODB_IDLE_TIMEOUT=30000 # Idle timeout in ms MONGODB_CONNECT_TIMEOUT=10000 # Connect timeout in ms MONGODB_SERVER_TIMEOUT=30000 # Server selection timeout in ms

=== Neo4j

[source,bash]

NEO4J_URL=bolt://localhost:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=secret

=== Elasticsearch

[source,bash]

ELASTICSEARCH_URL=http://localhost:9200 ELASTICSEARCH_USERNAME=elastic # optional ELASTICSEARCH_PASSWORD=secret # optional

=== Dragonfly / Redis

[source,bash]

DRAGONFLY_HOST=localhost DRAGONFLY_PORT=6379 DRAGONFLY_PASSWORD= # optional

=== InfluxDB

[source,bash]

INFLUXDB_URL=http://localhost:8086 INFLUXDB_TOKEN=your-token INFLUXDB_ORG=your-org INFLUXDB_BUCKET=your-bucket

=== SurrealDB

[source,bash]

SURREAL_URL=http://localhost:8000 SURREAL_NAMESPACE=test SURREAL_DATABASE=test SURREAL_USERNAME=root SURREAL_PASSWORD=root

=== ArangoDB

[source,bash]

ARANGO_URL=http://localhost:8529 ARANGO_DATABASE=_system ARANGO_USERNAME=root ARANGO_PASSWORD=

=== Virtuoso

[source,bash]

VIRTUOSO_ENDPOINT=http://localhost:8890/sparql VIRTUOSO_UPDATE_ENDPOINT=http://localhost:8890/sparql-auth VIRTUOSO_USERNAME= VIRTUOSO_PASSWORD= VIRTUOSO_DEFAULT_GRAPH=

=== CouchDB

[source,bash]

COUCHDB_URL=http://localhost:5984 COUCHDB_USERNAME=admin COUCHDB_PASSWORD=secret COUCHDB_DATABASE=mydb

=== Cassandra

[source,bash]

CASSANDRA_CONTACT_POINTS=localhost # comma-separated list CASSANDRA_DATACENTER=datacenter1 CASSANDRA_KEYSPACE=mykeyspace CASSANDRA_USERNAME=cassandra CASSANDRA_PASSWORD=cassandra

=== SQLite

[source,bash]

SQLITE_PATH=./data.db # or :memory:

=== DuckDB

[source,bash]

DUCKDB_PATH=./analytics.db # or :memory:

=== Qdrant

[source,bash]

QDRANT_URL=http://localhost:6333 QDRANT_API_KEY= # optional

=== Meilisearch

[source,bash]

MEILISEARCH_URL=http://localhost:7700 MEILISEARCH_API_KEY= # optional

=== MariaDB

[source,bash]

MARIADB_HOST=localhost MARIADB_PORT=3306 MARIADB_USER=root MARIADB_PASSWORD=secret MARIADB_DATABASE=mydb

Connection pool (optional)

MARIADB_POOL_MAX=10 # Max connections MARIADB_ACQUIRE_TIMEOUT=10000 # Acquire timeout in ms MARIADB_IDLE_TIMEOUT=30000 # Idle timeout in ms MARIADB_CONNECT_TIMEOUT=10000 # Connect timeout in ms

=== Memcached

[source,bash]

MEMCACHED_SERVERS=localhost:11211

=== LMDB

[source,bash]

LMDB_PATH=./lmdb-data

=== XTDB

[source,bash]

XTDB_URL=http://localhost:3000

=== iTop

[source,bash]

ITOP_URL=http://localhost/itop ITOP_USERNAME=admin ITOP_PASSWORD=secret

== Usage Examples

=== Meta Tools

db_list List all 18 supported databases db_status Check which databases are currently connected db_help [database] Get available tools for a specific database

=== Natural Language Queries

Ask Claude things like:

PostgreSQL:

[quote] Create a users table with id, email, and created_at columns

[quote] Find all orders over $100 from the last month

MongoDB:

[quote] Insert a new document into the products collection

[quote] Aggregate sales by category with a $match and $group pipeline

Neo4j:

[quote] Find the shortest path between User:alice and User:bob

[quote] Show all nodes connected to the 'Engineering' department

Elasticsearch:

[quote] Search for documents containing 'critical error' in the logs index

[quote] Get the mapping for the products index

Redis/Dragonfly:

[quote] Set user:123:session with a 30 minute TTL

[quote] Get all keys matching cache:*

Qdrant:

[quote] Search for vectors similar to this embedding in the documents collection

[quote] Create a new collection with 1536 dimensions for OpenAI embeddings

Cross-Database:

[quote] Query users from PostgreSQL and cache the result in Redis

[quote] Find products in MongoDB and index them in Meilisearch

== Architecture

polyglot-db-mcp/ ├── index.js # MCP server entry point ├── src/ # ReScript source (core adapters) │ ├── Adapter.res # Shared types │ ├── bindings/ # Database client FFI │ └── adapters/ # PostgreSQL, MongoDB, SQLite, Dragonfly, Elasticsearch ├── adapters/ # JavaScript adapters (exotic databases) ├── lib/es6/ # Compiled ReScript output └── STATE.scm # Project state tracking

=== Language Policy

[cols="1,1,2",options="header"] |=== |Component |Language |Rationale

|Core adapters (5) |ReScript |Type safety, smaller bundles |Exotic adapters (11) |JavaScript |Pragmatic for v1.x |Future (v2.0.0) |100% ReScript |RSR Gold compliance |===

IMPORTANT: TypeScript is prohibited. We chose ReScript for its superior type inference and ML heritage.

== Development

=== Building ReScript

[source,bash]

npm install # Install ReScript compiler npm run res:build # Compile to JavaScript npm run res:watch # Watch mode

=== Running Locally

[source,bash]

deno task start

or

deno run --allow-net --allow-read --allow-write --allow-env index.js

=== Git Hooks

Enable the pre-commit hook to enforce language policy:

[source,bash]

git config core.hooksPath .githooks

== Adding a New Database

Create src/adapters/YourDb.res:

[source,rescript]

// SPDX-License-Identifier: MIT open Adapter

let name = "yourdb" let description = "Your database description"

let connect = async () => { /* ... / } let disconnect = async () => { / ... / } let isConnected = async () => { / ... */ }

let tools: Js.Dict.t = { let dict = Js.Dict.empty() Js.Dict.set(dict, "yourdb_query", { description: "Execute a query", params: makeParams([("query", stringParam("Query to run"))]), handler: queryHandler, }) dict }

Then import in index.js and rebuild.

== Roadmap

[cols="1,1,3",options="header"] |=== |Version |Status |Highlights

|1.0.0 |Released |16 databases, ReScript core, CI/CD |1.1.0 |In Progress |Connection pooling, container images, better errors |1.2.0 |Planned |Cross-database pipelines, caching helpers |2.0.0 |Vision |100% ReScript, RSR Gold compliance, FormDB integration |===

=== FormDB Integration (v2.0.0)

https://github.com/hyperpolymath/formdb[FormDB] is a narrative-first, reversible, audit-grade database. When its API stabilizes, poly-db-mcp will add:

• formdb_query — Execute FQL queries with provenance
• formdb_explain — Get plan + reasons for queries
• formdb_introspect — Schema and constraint inspection
• formdb_journal — Access audit trail and reversibility primitives

== Related Projects

• https://github.com/hyperpolymath/arango-mcp[arango-mcp] — ArangoDB MCP server
• https://github.com/hyperpolymath/virtuoso-mcp[virtuoso-mcp] — Virtuoso SPARQL MCP server

== License

Dual-licensed: link:LICENSE.txt[MIT] OR link:LICENSE.txt[AGPL-3.0-or-later] — your choice.

We encourage (but don't require) layering the https://github.com/hyperpolymath/palimpsest-license[Palimpsest License] for ethical AI development practices.

© 2025 Jonathan D.A. Jewell (https://github.com/hyperpolymath[@hyperpolymath])