Allows AI agents to explore and query TimeBase streams, schemas, symbols, and run QQL queries.
Also known as epam/TimeBase-MCP, timebase-mcp
- Stars
- 8
- Tools
- —
- Downloads, 30 days
- 728
- Latest version
- 0.2.8
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is TimeBase MCP?
TimeBase allows AI agents to explore and query TimeBase streams, schemas, symbols, and run QQL queries.
Summary generated from the project's README
About TimeBase MCP server
TimeBase MCP provides a bridge for coding agents like Claude Desktop, Cursor, and VS Code to interact directly with TimeBase data. It enables an AI to navigate time-series information by listing available streams, reading schemas and symbols, and previewing messages. Developers can also execute QQL queries through the server to retrieve specific datasets for analysis.
This server supports two distinct deployment models depending on your requirements. You can run it locally as a stdio process for individual use with tools like Claude Code, or you can deploy it as a shared HTTP service for remote access by multiple users. This flexibility allows for both private local development and centralized team access to TimeBase resources.
What you can do with it
- 1Explore data structuresAsk your AI agent to list available streams and read their schemas to understand the data organization.
- 2Execute data queriesInstruct an AI client to run specific QQL queries to extract information from the time-series database.
- 3Inspect message contentHave the agent preview recent messages within a stream to verify data quality.
- 4Monitor server healthRequest a status report to check the current activity and health of the MCP server.
Written from the project's README. Every use case is checked against a quote from it.
How to install TimeBase MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall TimeBase MCP in Claude Code
$ claude mcp add --env 'TIMEBASE_OAUTH2_CLIENT_SECRET=<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>' --env 'TIMEBASE_PASSWORD=<YOUR_TIMEBASE_PASSWORD>' timebase-mcp -- uvx timebase-mcpInstall TimeBase MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"timebase-mcp": {
"command": "uvx",
"args": [
"timebase-mcp"
],
"env": {
"TIMEBASE_OAUTH2_CLIENT_SECRET": "<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>",
"TIMEBASE_PASSWORD": "<YOUR_TIMEBASE_PASSWORD>"
}
}
}
}Install TimeBase MCP in VS Code
.vscode/mcp.json
{
"servers": {
"timebase-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"timebase-mcp"
],
"env": {
"TIMEBASE_OAUTH2_CLIENT_SECRET": "<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>",
"TIMEBASE_PASSWORD": "<YOUR_TIMEBASE_PASSWORD>"
}
}
}
}Install TimeBase MCP in VS Code CLI
$ code --add-mcp '{"name":"timebase-mcp","type":"stdio","command":"uvx","args":["timebase-mcp"],"env":{"TIMEBASE_OAUTH2_CLIENT_SECRET":"<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>","TIMEBASE_PASSWORD":"<YOUR_TIMEBASE_PASSWORD>"}}'Install TimeBase MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"timebase-mcp": {
"command": "uvx",
"args": [
"timebase-mcp"
],
"env": {
"TIMEBASE_OAUTH2_CLIENT_SECRET": "<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>",
"TIMEBASE_PASSWORD": "<YOUR_TIMEBASE_PASSWORD>"
}
}
}
}Install TimeBase MCP in Codex
$ codex mcp add timebase-mcp --env 'TIMEBASE_OAUTH2_CLIENT_SECRET=<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>' --env 'TIMEBASE_OAUTH2_CLIENT_SECRET=<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>' --env 'TIMEBASE_PASSWORD=<YOUR_TIMEBASE_PASSWORD>' --env 'TIMEBASE_PASSWORD=<YOUR_TIMEBASE_PASSWORD>' -- uvx timebase-mcpInstall TimeBase MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.timebase-mcp] command = "uvx" args = ["timebase-mcp"] [mcp_servers.timebase-mcp.env] TIMEBASE_OAUTH2_CLIENT_SECRET = "<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>" TIMEBASE_PASSWORD = "<YOUR_TIMEBASE_PASSWORD>"
Install TimeBase MCP in Gemini CLI
$ gemini mcp add -s user -e 'TIMEBASE_OAUTH2_CLIENT_SECRET=<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>' -e 'TIMEBASE_OAUTH2_CLIENT_SECRET=<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>' -e 'TIMEBASE_PASSWORD=<YOUR_TIMEBASE_PASSWORD>' -e 'TIMEBASE_PASSWORD=<YOUR_TIMEBASE_PASSWORD>' timebase-mcp uvx -- timebase-mcpInstall TimeBase MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"timebase-mcp": {
"command": "uvx",
"args": [
"timebase-mcp"
],
"env": {
"TIMEBASE_OAUTH2_CLIENT_SECRET": "<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>",
"TIMEBASE_PASSWORD": "<YOUR_TIMEBASE_PASSWORD>"
}
}
}
}Configuration
TIMEBASE_OAUTH2_CLIENT_SECRETSecretOAuth2 client secret for service-account auth.
TIMEBASE_OAUTH2_CLIENT_SECRETSecretOAuth2 client secret for service-account auth.
TIMEBASE_PASSWORDSecretPassword for basic auth.
TIMEBASE_PASSWORDSecretPassword for basic auth.
MCP_AUTH_API_KEYS_FILEPath to a hashed API-key store for inbound bearer-key auth.
MCP_AUTH_AUDIENCEExpected JWT audience for inbound IdP auth.
MCP_AUTH_ISSUER_URLOAuth issuer URL override for inbound JWT authentication.
MCP_AUTH_JWKS_URLJWKS URL override for inbound JWT authentication.
MCP_AUTH_PUBLIC_URLPublic HTTPS URL of this MCP endpoint (e.g. https://mcp.example.com/mcp).
MCP_AUTH_REQUIRED_SCOPESRequired OAuth permissions, separated by spaces or commas.
MCP_AUTH_SCOPE_ALIASESJSON object mapping required permissions to delegated JWT scp values.
MCP_HOSTLoopback host for interactive OAuth redirect in stdio mode.
MCP_LOG_LEVELLog level: DEBUG, INFO, WARNING, ERROR, or CRITICAL.
MCP_LOG_LEVELLog level: DEBUG, INFO, WARNING, ERROR, or CRITICAL.
MCP_PORTLoopback port for interactive OAuth redirect in stdio mode.
TIMEBASE_AUTH_MODEOutbound auth: auto, none, basic, oauth2_client_credentials, interactive.
TIMEBASE_AUTH_MODEOutbound auth: auto, none, basic, oauth2_client_credentials, forward_identity.
TIMEBASE_OAUTH2_CLIENT_IDOAuth2 client ID for service-account or interactive login.
TIMEBASE_OAUTH2_CLIENT_IDOAuth2 client ID for service-account or interactive login.
TIMEBASE_OAUTH2_SCOPEOAuth2 scope(s) for service-account or interactive login.
TIMEBASE_OAUTH2_SCOPEOAuth2 scope(s) for service-account or interactive login.
TIMEBASE_OAUTH2_TOKEN_URLOAuth2 token endpoint for service-account client credentials.
TIMEBASE_OAUTH2_TOKEN_URLOAuth2 token endpoint for service-account client credentials.
TIMEBASE_SERVERSMulti-server config as a JSON array string or path to a JSON file.
TIMEBASE_SERVERSMulti-server config as a JSON array string or path to a JSON file.
TIMEBASE_URLTimeBase native connection URL.
TIMEBASE_URLTimeBase native connection URL.
TIMEBASE_USERNAMEUsername for basic auth or oauth2_client_credentials.
TIMEBASE_USERNAMEUsername for basic auth or oauth2_client_credentials.
| Name | Description | |
|---|---|---|
| TIMEBASE_OAUTH2_CLIENT_SECRET | OAuth2 client secret for service-account auth. | Secret |
| TIMEBASE_OAUTH2_CLIENT_SECRET | OAuth2 client secret for service-account auth. | Secret |
| TIMEBASE_PASSWORD | Password for basic auth. | Secret |
| TIMEBASE_PASSWORD | Password for basic auth. | Secret |
| MCP_AUTH_API_KEYS_FILE | Path to a hashed API-key store for inbound bearer-key auth. | |
| MCP_AUTH_AUDIENCE | Expected JWT audience for inbound IdP auth. | |
| MCP_AUTH_ISSUER_URL | OAuth issuer URL override for inbound JWT authentication. | |
| MCP_AUTH_JWKS_URL | JWKS URL override for inbound JWT authentication. | |
| MCP_AUTH_PUBLIC_URL | Public HTTPS URL of this MCP endpoint (e.g. https://mcp.example.com/mcp). | |
| MCP_AUTH_REQUIRED_SCOPES | Required OAuth permissions, separated by spaces or commas. | |
| MCP_AUTH_SCOPE_ALIASES | JSON object mapping required permissions to delegated JWT scp values. | |
| MCP_HOST | Loopback host for interactive OAuth redirect in stdio mode. | |
| MCP_LOG_LEVEL | Log level: DEBUG, INFO, WARNING, ERROR, or CRITICAL. | |
| MCP_LOG_LEVEL | Log level: DEBUG, INFO, WARNING, ERROR, or CRITICAL. | |
| MCP_PORT | Loopback port for interactive OAuth redirect in stdio mode. | |
| TIMEBASE_AUTH_MODE | Outbound auth: auto, none, basic, oauth2_client_credentials, interactive. | |
| TIMEBASE_AUTH_MODE | Outbound auth: auto, none, basic, oauth2_client_credentials, forward_identity. | |
| TIMEBASE_OAUTH2_CLIENT_ID | OAuth2 client ID for service-account or interactive login. | |
| TIMEBASE_OAUTH2_CLIENT_ID | OAuth2 client ID for service-account or interactive login. | |
| TIMEBASE_OAUTH2_SCOPE | OAuth2 scope(s) for service-account or interactive login. | |
| TIMEBASE_OAUTH2_SCOPE | OAuth2 scope(s) for service-account or interactive login. | |
| TIMEBASE_OAUTH2_TOKEN_URL | OAuth2 token endpoint for service-account client credentials. | |
| TIMEBASE_OAUTH2_TOKEN_URL | OAuth2 token endpoint for service-account client credentials. | |
| TIMEBASE_SERVERS | Multi-server config as a JSON array string or path to a JSON file. | |
| TIMEBASE_SERVERS | Multi-server config as a JSON array string or path to a JSON file. | |
| TIMEBASE_URL | TimeBase native connection URL. | |
| TIMEBASE_URL | TimeBase native connection URL. | |
| TIMEBASE_USERNAME | Username for basic auth or oauth2_client_credentials. | |
| TIMEBASE_USERNAME | Username for basic auth or oauth2_client_credentials. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableepam/timebase-mcp is public and reachablegithub.com/epam/timebase-mcp ↗Pass
- Package names this repository as its sourcetimebase-mcp names epam/timebase-mcp as sourcepypi.org/project/timebase-mcp/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for timebase-mcppypi.org/project/timebase-mcp/ ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/epam/timebase-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from timebase-mcpPass
- No critical advisory in the package or its dependencies39 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubTimeBase MCP
A Model Context Protocol server that lets a coding agent (Claude Code, VS Code, Cursor, Claude Desktop, etc.) explore and query TimeBase: list streams, read schemas and symbols, preview messages, run QQL queries, and inspect server status and activity.
The server can run two ways:
- Locally, your agent launches
timebase-mcpas a local process (stdio) that connects to your TimeBase. - Remotely, you deploy
timebase-mcpas a shared HTTP service that multiple users connect their agents to.
Which guide do I need?
| You want to | Go to |
|---|---|
| Use TimeBase MCP locally (Cursor, VS Code, Claude Code/Desktop) | Agent Plugins Quickstart |
| Manual local setup | Local setup |
| Deploy a shared remote MCP server | Remote deployment |
| Connect to a running remote server | Connect to a remote server |
| Add optional WebAdmin inspection | Add WebAdmin access |
Documentation
| Topic | Go to |
|---|---|
| Updating | Local setup: Updating |
| Troubleshooting | Troubleshooting |
| Reference | Environment variables, auth, capabilities |
See also
TimeBase MCP questions
How do I add TimeBase MCP to Claude Code?
Run claude mcp add --env 'TIMEBASE_OAUTH2_CLIENT_SECRET=<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>' --env 'TIMEBASE_PASSWORD=<YOUR_TIMEBASE_PASSWORD>' timebase-mcp -- uvx timebase-mcp in your terminal. Add --scope user to make it available in every project.
How do I add TimeBase MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What can I do with the TimeBase MCP server?
You can list streams, read schemas and symbols, preview messages, run QQL queries, and inspect server status and activity.