# TimeBase MCP server

> Allows AI agents to explore and query TimeBase streams, schemas, symbols, and run QQL queries.

- Repository: https://github.com/epam/TimeBase-MCP
- Page: https://hostedmcp.org/servers/epam/timebase-mcp
- Transport: stdio, remote
- Stars: 8
- License: Apache-2.0
- Latest version: 0.2.8

## Install

### Claude Code

```sh
claude mcp add --env 'TIMEBASE_OAUTH2_CLIENT_SECRET=<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>' --env 'TIMEBASE_PASSWORD=<YOUR_TIMEBASE_PASSWORD>' timebase-mcp -- uvx timebase-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "timebase-mcp": {
      "command": "uvx",
      "args": [
        "timebase-mcp"
      ],
      "env": {
        "TIMEBASE_OAUTH2_CLIENT_SECRET": "<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>",
        "TIMEBASE_PASSWORD": "<YOUR_TIMEBASE_PASSWORD>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```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>"
      }
    }
  }
}
```

### VS Code CLI

```sh
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>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "timebase-mcp": {
      "command": "uvx",
      "args": [
        "timebase-mcp"
      ],
      "env": {
        "TIMEBASE_OAUTH2_CLIENT_SECRET": "<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>",
        "TIMEBASE_PASSWORD": "<YOUR_TIMEBASE_PASSWORD>"
      }
    }
  }
}
```

### Codex

```sh
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-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```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>"
```

### Gemini CLI

```sh
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-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "timebase-mcp": {
      "command": "uvx",
      "args": [
        "timebase-mcp"
      ],
      "env": {
        "TIMEBASE_OAUTH2_CLIENT_SECRET": "<YOUR_TIMEBASE_OAUTH2_CLIENT_SECRET>",
        "TIMEBASE_PASSWORD": "<YOUR_TIMEBASE_PASSWORD>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `TIMEBASE_OAUTH2_CLIENT_SECRET` | no | yes | OAuth2 client secret for service-account auth. |
| `TIMEBASE_OAUTH2_CLIENT_SECRET` | no | yes | OAuth2 client secret for service-account auth. |
| `TIMEBASE_PASSWORD` | no | yes | Password for basic auth. |
| `TIMEBASE_PASSWORD` | no | yes | Password for basic auth. |
| `MCP_AUTH_API_KEYS_FILE` | no | no | Path to a hashed API-key store for inbound bearer-key auth. |
| `MCP_AUTH_AUDIENCE` | no | no | Expected JWT audience for inbound IdP auth. |
| `MCP_AUTH_ISSUER_URL` | no | no | OAuth issuer URL override for inbound JWT authentication. |
| `MCP_AUTH_JWKS_URL` | no | no | JWKS URL override for inbound JWT authentication. |
| `MCP_AUTH_PUBLIC_URL` | no | no | Public HTTPS URL of this MCP endpoint (e.g. https://mcp.example.com/mcp). |
| `MCP_AUTH_REQUIRED_SCOPES` | no | no | Required OAuth permissions, separated by spaces or commas. |
| `MCP_AUTH_SCOPE_ALIASES` | no | no | JSON object mapping required permissions to delegated JWT scp values. |
| `MCP_HOST` | no | no | Loopback host for interactive OAuth redirect in stdio mode. |
| `MCP_LOG_LEVEL` | no | no | Log level: DEBUG, INFO, WARNING, ERROR, or CRITICAL. |
| `MCP_LOG_LEVEL` | no | no | Log level: DEBUG, INFO, WARNING, ERROR, or CRITICAL. |
| `MCP_PORT` | no | no | Loopback port for interactive OAuth redirect in stdio mode. |
| `TIMEBASE_AUTH_MODE` | no | no | Outbound auth: auto, none, basic, oauth2_client_credentials, interactive. |
| `TIMEBASE_AUTH_MODE` | no | no | Outbound auth: auto, none, basic, oauth2_client_credentials, forward_identity. |
| `TIMEBASE_OAUTH2_CLIENT_ID` | no | no | OAuth2 client ID for service-account or interactive login. |
| `TIMEBASE_OAUTH2_CLIENT_ID` | no | no | OAuth2 client ID for service-account or interactive login. |
| `TIMEBASE_OAUTH2_SCOPE` | no | no | OAuth2 scope(s) for service-account or interactive login. |
| `TIMEBASE_OAUTH2_SCOPE` | no | no | OAuth2 scope(s) for service-account or interactive login. |
| `TIMEBASE_OAUTH2_TOKEN_URL` | no | no | OAuth2 token endpoint for service-account client credentials. |
| `TIMEBASE_OAUTH2_TOKEN_URL` | no | no | OAuth2 token endpoint for service-account client credentials. |
| `TIMEBASE_SERVERS` | no | no | Multi-server config as a JSON array string or path to a JSON file. |
| `TIMEBASE_SERVERS` | no | no | Multi-server config as a JSON array string or path to a JSON file. |
| `TIMEBASE_URL` | no | no | TimeBase native connection URL. |
| `TIMEBASE_URL` | no | no | TimeBase native connection URL. |
| `TIMEBASE_USERNAME` | no | no | Username for basic auth or oauth2_client_credentials. |
| `TIMEBASE_USERNAME` | no | no | Username for basic auth or oauth2_client_credentials. |

## FAQ

### 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.
