Periscope MCP server
Commit Nov 14, 2026Provides AI agents with strictly read-only query access to diverse data sources including PostgreSQL, Oracle, SQL Server, Cosmos DB, and Redis.
Also known as coreprocess/periscope-mcp
- Stars
- 0
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is Periscope MCP?
Periscope provides AI agents with strictly read-only query access to diverse data sources including PostgreSQL, Oracle, SQL Server, Cosmos DB, and Redis. It exposes 6 tools, such as list_sources, describe, query.
Summary generated from the project's README
About Periscope MCP server
Providing AI agents with strictly read-only access to diverse data sources is what periscope-mcp enables for developers and data engineers. It connects agents to PostgreSQL, Oracle, SQL Server, Cosmos DB, Redis, Azure Blob Storage, and even custom HTTP APIs. By using specific tools like list_sources, describe, and query, an agent can explore schemas and execute single SELECT statements or specific Redis commands without any risk of modifying the underlying data.
Users can run this server locally using Node.js and pnpm via stdio, or deploy it using Docker for remote access. The system is designed to handle massive datasets by never returning data inline; instead, it produces a result that an agent can page through using read_result or download via a manifest URL for processing with tools like DuckDB or pandas. Security is enforced through multiple layers, including transaction rollbacks and strict syntax filtering, ensuring that even if a credential has write permissions, the agent remains restricted to read operations.
What you can do with it
- 1Exploring database schemasAn AI agent can investigate table structures and column definitions across different databases to understand available data.
- 2Querying large datasetsDevelopers can instruct an agent to run a query and then download the resulting files for heavy-duty analysis.
- 3Monitoring cloud logsUsers can use KQL to pull insights from Azure Log Analytics or Application Insights.
Written from the project's README. Every use case is checked against a quote from it.
Periscope MCP tools 6
Detected from the READMElist_sourcesdescribequeryget_resultread_resultcancel_query
Configuration
PERISCOPE_SOURCE_0_NAMEPERISCOPE_SOURCE_0_TYPEPERISCOPE_SOURCE_0_URLPERISCOPE_SOURCE_1_NAMEPERISCOPE_SOURCE_1_TYPEPERISCOPE_SOURCE_1_URLPERISCOPE_SOURCE_N
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecoreprocess/periscope-mcp is public and reachablegithub.com/coreprocess/periscope-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-28github.com/coreprocess/periscope-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPeriscope MCP
Periscope is an MCP server that gives AI agents strictly read-only query access to data sources:
| Source | Query language | Result format |
|---|---|---|
| PostgreSQL | SQL (one SELECT) |
Parquet |
| Oracle Database (19c+) | SQL (one SELECT) |
Parquet |
| SQL Server / Azure SQL | T-SQL (one SELECT) |
Parquet |
| Azure Cosmos DB for NoSQL | Cosmos NoSQL query language | NDJSON (gzip) |
| Azure Blob Storage | Glob or prefix, optional tag filter | NDJSON listing; contents referenced in place |
| Azure Log Analytics / Application Insights | KQL | Parquet |
| Redis (standalone or cluster) | One read-only Redis command; SCAN as key export |
NDJSON (gzip) |
| KIM | Node or record query language | NDJSON (gzip); offloaded contents referenced in place |
Any HTTP API (rest) |
One HTTP request: request line, headers, body | NDJSON (gzip); binary responses referenced, fetched again on read |
Agents get the full read capability of each source. Writes cannot get through: on the API-based sources, write operations are never offered and are blocked on the wire; on the query-language sources they are filtered at several independent layers; for HTTP APIs, only the requests the operator declares as reads are sent. The guarantee holds even when the configured credential could write.
A query never returns data inline. It produces a result that the agent either pages through in small windows (read_result) or downloads over HTTP and processes with its own tools (curl, DuckDB, jq, pandas). The flow is the same for five rows or fifty million.
The full design is in docs/CONCEPT.md.
Tools
| Tool | Purpose |
|---|---|
list_sources |
Sources you may query, with query language, dialect hints, options and limits |
describe |
Metadata, drilled down step by step (schemas → tables → columns, containers → sampled schemas, prefixes, …) |
query |
Starts a query and returns a resultId immediately; non-read-only queries are rejected synchronously |
get_result |
Status, schema, row counts, window limits and one manifest URL for downloads |
read_result |
One window of rows, or (blob, KIM and REST results) lines of a text file or an image |
cancel_query |
Stops a running query |
A typical session:
list_sources() → appdata (cosmos), erp (oracle), …
describe("appdata", "main/claims") → partition key, inferred schema
query("appdata", "SELECT * FROM c WHERE c.year = @y",
{ "@y": 2026 }, { "container": "claims" }) → r_7Hq2kV…
read_result("r_7Hq2kV…", limit: 20) → first rows (already while running)
get_result("r_7Hq2kV…", wait: 10) → succeeded, 1.8M rows, 19 files, 412 MB
M="<download.manifestUrl>"; B="${M%/manifest.json}"
curl -fsS "$M" | jq -r '.files[].path' | xargs -P4 -I{} curl -fsS --create-dirs -o {} "$B/{}"
duckdb -c "SELECT status, count(*) FROM read_json('part-*.ndjson.gz') GROUP BY 1"
Run locally (stdio)
Requires Node.js 24 and pnpm.
pnpm install
cp .env.example .env.periscope # add your sources
node src/index.ts --env-file .env.periscope
Register it with Claude Code:
claude mcp add periscope -- node /path/to/periscope-mcp/src/index.ts --env-file /path/to/.env.periscope
In stdio mode, results are stored in ./.periscope/results and download URLs point to a small HTTP endpoint on 127.0.0.1 that the server starts alongside.
With Docker (the published image runs the HTTP transport by default):
docker run -i --rm --env-file .env.periscope \
-e PERISCOPE_TRANSPORT=stdio -e PERISCOPE_HOST=0.0.0.0 -e PERISCOPE_PORT=8765 \
-e PERISCOPE_PUBLIC_URL=http://127.0.0.1:8765 -p 127.0.0.1:8765:8765 \
ghcr.io/coreprocess/periscope-mcp:0.1.0
Deploy
Periscope is built to run as one container per project and environment, inside the network where the data sources are reachable, protected by Microsoft Entra ID (OAuth 2.1, MCP authorization spec): directly when the host is on a domain verified in the tenant, otherwise through Periscope's built-in authorization server, which signs users in at Entra (PERISCOPE_AUTH=entra-broker). See docs/deployment.md and the Terraform module in terraform/.
Configuration
Everything is configured through environment variables; sources are an indexed list:
PERISCOPE_SOURCE_N=2
PERISCOPE_SOURCE_0_NAME=shop
PERISCOPE_SOURCE_0_TYPE=postgres
PERISCOPE_SOURCE_0_URL=postgres://reader:secret@db:5432/shop
PERISCOPE_SOURCE_1_NAME=cache
PERISCOPE_SOURCE_1_TYPE=redis
PERISCOPE_SOURCE_1_URL=rediss://default:secret@cache:6380
The full reference is in docs/configuration.md.
How read-only is enforced
| Source | Layers |
|---|---|
| Cosmos DB | Only read/query operations implemented; HTTP guard on the SDK lets only GET/HEAD and query POSTs through |
| Blob Storage | Only list/read operations implemented; pipeline guard lets only GET/HEAD through; downloads pinned to ETag/version/snapshot |
| Log Analytics | Query API only (it has no write operations); control commands rejected |
| PostgreSQL | READ ONLY transaction, always rolled back; syntax-tree guard with the Postgres parser (single SELECT, no locking, no data-modifying CTEs); side-effect function denylist; inventory that parses view definitions and switches to strict mode when dblink-style functions are reachable |
| Oracle | SET TRANSACTION READ ONLY, always rolled back; strict lexer (single SELECT, no PL/SQL, no DML/DDL keywords, no FOR UPDATE, no NEXTVAL); system package allowlist; routine inventory against autonomous transactions and dynamic SQL |
| SQL Server | Transaction that is always rolled back; strict T-SQL lexer (single SELECT, no EXEC, no DML/DDL, no SELECT … INTO, no NEXT VALUE FOR, no remote rowsets or locking hints); function inventory against extended procedures, OLE Automation, CLR and linked servers, with strict mode for sysadmin logins and risky server settings; optional ApplicationIntent=ReadOnly |
| Redis | Static allowlist of read-only, non-blocking commands; guard on every command the client writes to the socket; optional replica reads |
| KIM | Service account key with only the Reader role; allowlist on every HTTP request (query, collection listing, type definitions, byte reads; no drafts, sessions, agents or exports); query check (no reveal unless allowed, no foreign origins) |
| REST | Operator-declared allowlist of METHOD pattern rules, checked on every request, page, redirect hop and file read; no method override headers or parameters, no dot segments or encoded slashes; agents cannot set credentials; optional script check. Holds as far as the allowed requests are reads for the API. |
Each layer is tested on its own against real databases with write-capable credentials (see test/integration).
Development
pnpm lint # Biome
pnpm typecheck # TypeScript
pnpm test # unit tests
pnpm test:integration # needs Docker: Postgres, Oracle, SQL Server, Cosmos emulator, Azurite, Redis; KIM and REST run against mocks
pnpm build
License
MIT
Periscope MCP questions
What tools does Periscope MCP provide?
It exposes 6 tools, including list_sources, describe, query, get_result, read_result.
How are query results returned to the agent?
Queries do not return data inline; instead, they produce a result that the agent can page through in small windows or download via HTTP for processing.
What authentication methods are supported?
The server supports Microsoft Entra ID (OAuth 2.1) and can use a built-in authorization server to sign users in via Entra.