Turnkey Read-Only MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Turnkey Read-Only MCP Server
A self-hosted, read-only MCP server that lets any MCP client answer questions about your Turnkey organization:
How many sub-organizations do we have, and how many are created each month?
How many wallets / wallet accounts per sub-org?
How many signatures per month, and how many are mainnet vs testnet?
How many sub-orgs were active in the last 30 days?
How many sub-orgs should we expect in 3 and 6 months?
It only calls Turnkey query endpoints (/public/v1/query/*). There is no code path that submits an activity, so it cannot sign, create, or delete anything.
How it works
MCP client ──HTTPS──▶ /mcp (Streamable HTTP, OAuth 2.1) ──▶ in-memory snapshot
▲
background scanner (every 60 min) ┘──▶ Turnkey query APIScanning a large organization takes many API calls, so a background job builds a snapshot at startup and refreshes it periodically. Tool calls answer instantly from that snapshot; refresh_data forces a new scan.
Related MCP server: meta-horizon-developer-mcp
Tools
Tool | What it returns |
| Everything below in one call. Start here. |
| Sub-orgs today, created per month, average of the last 3 full months, current-month pace. |
| Sub-orgs expected in N months (linear at the recent rate, optional |
| Wallets and accounts per sub-org (avg, median, p90, max, histogram), accounts by address format. |
| Signatures per month and last 30 days, split mainnet / testnet / unknown, by type and by network. |
| Sub-orgs with any activity, and with at least one signature, in the last N days. |
| Starts a new scan and reports progress. |
1. Create a dedicated, non-root Turnkey user
⚠️ Do not use an API key on your Root user. Root users bypass Turnkey's policy engine, so a leaked root key can sign transactions and change your organization.
Turnkey query endpoints are not subject to the policy engine: any authenticated user in the organization can read its data, and the parent organization can read all of its sub-organizations. Activities (signing, creating, deleting), on the other hand, are deny-by-default for non-root users. So a non-root user with no policies is effectively a read-only user.
In the Turnkey dashboard, go to Users and add a new user, e.g.
mcp-readonly.Do not add it to the root quorum. Do not give it tags or policies.
Open that user and create an API key for it. Copy the public and private key (the private key is shown only once).
Copy your parent organization ID (user menu, top right).
Optional but recommended: review Policies and make sure no existing policy allows activities for all users (e.g. a policy whose consensus is
true), which would also apply to this user.
If the key ever leaks, an attacker can read your organization's metadata (sub-org IDs, addresses, activity history) but cannot move funds. Delete the key in the dashboard to revoke it.
2. Configure
cp .env.example .env
openssl rand -hex 32 # paste as MCP_AUTH_TOKENVariable | Required | Description |
| ✅ | Parent organization ID |
| ✅ | Public key of the non-root user's API key |
| ✅ | Private key of that API key |
| ✅ | Access token (≥ 32 chars): typed on the sign-in page, or sent as a bearer token |
| ✅ | Public base URL, e.g. |
| Default | |
| Reverse proxies in front of the app. Default | |
| Signing history kept in memory. Default | |
| Background refresh. Default | |
| Parallel Turnkey requests. Default | |
| Extra EVM chain IDs to classify, comma-separated |
3. Run
Locally (Node ≥ 20):
npm ci
npm run dev
curl http://localhost:3000/healthDocker:
docker compose up -d --build4. Deploy
The image is a plain Docker container listening on PORT (default 3000), so it runs on any Docker host or PaaS (Dokploy, Coolify, Railway, Fly.io, a VPS with Compose, ...):
Push this repo to GitHub/GitLab (your fork is fine;
.envis git-ignored).Create an application that builds from the
Dockerfile, or a Compose service fromdocker-compose.yml.Set the environment variables from your
.env.Put it behind your domain (e.g.
turnkey-mcp.example.com) with HTTPS, pointing at container port3000.Check
https://turnkey-mcp.example.com/health;snapshotbecomes a timestamp when the first scan finishes.
Always serve the MCP endpoint over HTTPS, and set
PUBLIC_URLto that HTTPS address.
5. Connect an MCP client
The MCP endpoint is https://your-domain/mcp (Streamable HTTP). It follows the MCP authorization spec (OAuth 2.1), so there are two ways in:
OAuth (clients that support it): add only the URL https://your-domain/mcp. The client discovers the authorization server, registers itself and opens a sign-in page in your browser. Paste MCP_AUTH_TOKEN there once. The client then gets its own access token (1 hour) and refresh token (30 days) and renews them on its own.
Bearer header (clients that take custom headers): send MCP_AUTH_TOKEN directly. Most clients take a JSON config like this:
{
"mcpServers": {
"turnkey": {
"type": "http",
"url": "https://your-domain/mcp",
"headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
}
}
}Then ask your assistant for the Turnkey usage summary.
The token never goes in the URL. Every person you give MCP_AUTH_TOKEN to gets the same read-only access. To cut everyone off, set a new MCP_AUTH_TOKEN and restart: all OAuth tokens are signed with a key derived from it, so they stop working at once.
How the numbers are calculated
Sub-orgs today:
list_suborgson the parent organization.Created per month: dates of completed
CREATE_SUB_ORGANIZATION*activities in the parent. Sub-orgs without such an activity fall back to their earliest wallet's creation date (reported in the output).Wallets per sub-org:
list_walletsandlist_wallet_accountsfor every sub-org.Signatures: completed signing activities (
SIGN_RAW_PAYLOAD*,SIGN_TRANSACTION*,ETH_SEND_*,SOL_SEND_*) in the parent and every sub-org.SIGN_RAW_PAYLOADScounts each payload. Totals may differ slightly from the dashboard's billing counter.Mainnet vs testnet: known only when Turnkey sees the network: send-transaction activities carry a CAIP-2 chain ID, and EVM unsigned transactions are decoded for their chain ID (classified with viem's chain registry). Raw-payload and message signatures, and Solana
SIGN_TRANSACTION, don't include the network and are reported asunknown. If most of your volume is raw payloads, get the split from your own backend.Active sub-orgs: a sub-org with any activity (session/login, signing, wallet creation…) in the window; also reported: sub-orgs with at least one signature.
Projection: today + average new sub-orgs per month over the last 3 full months × months; optionally with a month-over-month growth rate.
All months are UTC.
Troubleshooting
/healthshowsphase: "failed": check the organization ID and API key; therefresh_datatool showslast_error.Rate-limit errors: lower
SCAN_CONCURRENCY.401 from
/mcp: the bearer token doesn't matchMCP_AUTH_TOKEN, or the OAuth token expired and the client didn't refresh it (reconnect it).OAuth sign-in fails or redirects to the wrong host:
PUBLIC_URLmust be the exact public HTTPS address clients use.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only analytics for Convex apps, queryable via MCP from Claude, Cursor, and other clients.
Read-only Google Analytics 4 MCP server for AI assistants.
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Related MCP Servers
- AlicenseBqualityDmaintenanceRead-only MCP server for querying Shopify analytics data, including orders, customers, products, sales, retention, and attribution.19MIT
- FlicenseCqualityCmaintenanceRead-only MCP server that collects Analytics data from the Meta Horizon developer dashboard by intercepting GraphQL queries. It provides tools for status checks, snapshot collection, and reading allowed query results.4-
- FlicenseNot gradedqualityCmaintenanceEnables read-only access to Addepar portfolio and ownership data for financial reporting, with transparent provenance caveats and compliance-oriented audit logging.-
- AlicenseAqualityBmaintenanceEnables MCP clients to query Google Analytics 4 reporting and configuration data through 27 read-only tools, including pivots, funnels, realtime reports, Admin API inspection, and diagnostics, with identifiers redacted by default.27409 npmApache 2.0