TimeBase MCP

Prerequisites

• Python >=3.10
• One of the following:
  • pip
  • uv
  • pipx

Installation

Tip

If you're planning to work with both TimeBase Community and Enterprise servers, you can install both editions by replacing [enterprise] with [all] in the commands below. MCP server will automatically select the correct edition to use based on the connected TimeBase server.

Already installed? See Updating an Existing Installation.

Important

Make sure to replace <user> and <password> with your Nexus credentials when installing the enterprise edition.

Using pip

Community edition:

python -m pip install "timebase-mcp[community]"

Enterprise edition:

python -m pip install --extra-index-url "https://<user>:<password>@nexus.deltixhub.com/repository/epm-rtc-public-python/simple" "timebase-mcp[enterprise]"

If you get an error about environment being managed externally, follow the uv or pipx instructions instead.

Warning

Do NOT create a virtual environment manually when using pip, as MCP server needs to be globally accessible in PATH. If you want to isolate dependencies, use pipx or uv which handle this automatically.

Using uv

Community edition:

uv tool install -p 3.14 --from "timebase-mcp[community]" timebase-mcp

Enterprise edition:

uv tool install -p 3.14 --index "https://<user>:<password>@nexus.deltixhub.com/repository/epm-rtc-public-python/simple" --from "timebase-mcp[enterprise]" timebase-mcp

Using pipx

Community edition:

pipx install --python 3.14 "timebase-mcp[community]"

Enterprise edition:

pipx install --python 3.14 --pip-args "--extra-index-url https://<user>:<password>@nexus.deltixhub.com/repository/epm-rtc-public-python/simple" "timebase-mcp[enterprise]"

Note

MCP server will be launched from MCP client (coding agent) automatically, but the installed timebase-mcp must be in PATH. After installation you can verify that the server is correctly installed and accessible by running the following command from a new terminal:

timebase-mcp -v

Updating an Existing Installation

Use the command for your package manager to update timebase-mcp to the latest available version.

Using pip

Community edition:

python -m pip install --upgrade "timebase-mcp[community]"

Enterprise edition:

python -m pip install --upgrade --extra-index-url "https://<user>:<password>@nexus.deltixhub.com/repository/epm-rtc-public-python/simple" "timebase-mcp[enterprise]"

Using uv

Community edition:

uv tool upgrade -p 3.14 timebase-mcp

Enterprise edition:

uv tool upgrade -p 3.14 --index "https://<user>:<password>@nexus.deltixhub.com/repository/epm-rtc-public-python/simple" timebase-mcp

Using pipx

Community edition:

pipx upgrade --python 3.14 "timebase-mcp"

Enterprise edition:

pipx upgrade --python 3.14 --pip-args "--extra-index-url https://<user>:<password>@nexus.deltixhub.com/repository/epm-rtc-public-python/simple" "timebase-mcp"

After updating, run timebase-mcp -v from a new terminal to verify the installed version and PATH access.

Basic Configuration

For no-auth and basic-auth setups, use these variables in your MCP config:

Variable	Default value	Description
TIMEBASE_URL	dxtick://localhost:8011	TimeBase connection URL
TIMEBASE_USERNAME	None	Username for basic auth
TIMEBASE_PASSWORD	None	Password for basic auth

If your server does not require authentication, set only TIMEBASE_URL.

For more options, including OAuth2, see Advanced Configuration.

MCP Client Configuration

Follow the instructions for your MCP client to configure the server.

VS Code

Create .vscode/mcp.json:

{
  "servers": {
    "timebase-mcp": {
      "type": "stdio",
      "command": "timebase-mcp",
      "args": [],
      "env": {
        "TIMEBASE_URL": "dxtick://localhost:8011"
      }
    }
  }
}

Cursor

Click the button to install

Or manually create .cursor/mcp.json

{
  "mcpServers": {
    "timebase-mcp": {
      "type": "stdio",
      "command": "timebase-mcp",
      "args": [],
      "env": {
        "TIMEBASE_URL": "dxtick://localhost:8011"
      }
    }
  }
}

Claude Desktop

Available options: Claude Desktop config and MCP Bundle.

MCP Config

Follow the official guide for your OS, for the configuration use the following:

{
  "mcpServers": {
    "timebase-mcp": {
      "command": "timebase-mcp",
      "args": [],
      "env": {
        "TIMEBASE_URL": "dxtick://localhost:8011"
      }
    }
  }
}

MCP Bundle

This currently requires Node.js and uv to be installed.

1. Run the following command in this repo to create the bundle:

npx @anthropic-ai/mcpb pack

2. In Claude Desktop go to Settings > Extensions > Advanced settings > Install extension and select the .mcpb file generated in step 1.

Claude Code

claude mcp add timebase-mcp --transport stdio --env TIMEBASE_URL='dxtick://localhost:8011' -- timebase-mcp

[!NOTE] This command adds a local-scoped server (current project and user only). There're also project and user scopes, specify them via a --scope local|project|user flag. Check out the official documentation for more details.

Opencode

Add the following to your opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "timebase-mcp": {
      "type": "local",
      "command": "timebase-mcp",
      "enabled": true,
      "environment": {
        "TIMEBASE_URL": "dxtick://localhost:8011",
      },
    },
  },
}

Advanced Configuration

Use these variables for configuring the MCP server:

Variable	Default value	Description
TIMEBASE_URL	dxtick://localhost:8011	TimeBase connection URL
TIMEBASE_USERNAME	None	Username for basic auth. Optional for OAuth2; when omitted, defaults to TIMEBASE_OAUTH2_CLIENT_ID
TIMEBASE_PASSWORD	None	Password for basic auth. Mutually exclusive with the OAuth2 settings
TIMEBASE_OAUTH2_TOKEN_URL	None	OAuth2 token endpoint for auth using the client credentials flow
TIMEBASE_OAUTH2_CLIENT_ID	None	OAuth2 client ID
TIMEBASE_OAUTH2_CLIENT_SECRET	None	OAuth2 client secret
TIMEBASE_OAUTH2_SCOPE	None	Optional space-delimited OAuth2 scopes
TIMEBASE_OAUTH2_TOKEN_PARAMS	None	Optional JSON object of extra OAuth2 token form parameters
MCP_LOG_LEVEL	INFO	Log verbosity: DEBUG, INFO, WARNING, ERROR, or CRITICAL

Important

Enterprise connections may need extra SSL environment variables that are handled by dxapi. This includes DXAPI_SSL_TERMINATION, DXAPI_SSL_TRUST_ALL, SSL_CERT_FILE, etc. See dxapi environment variables and SSL configuration.

OAuth2 Client Credentials

OAuth2 works only with the enterprise dxapi client. timebase-mcp uses the client credentials flow and currently supports the client_secret_post token-endpoint authentication method.

Required variables:

• TIMEBASE_OAUTH2_TOKEN_URL
• TIMEBASE_OAUTH2_CLIENT_ID
• TIMEBASE_OAUTH2_CLIENT_SECRET

Optional variables:

• TIMEBASE_USERNAME to override the default TimeBase username; otherwise TIMEBASE_OAUTH2_CLIENT_ID is used
• TIMEBASE_OAUTH2_SCOPE as a single space-delimited string when multiple scopes are required
• TIMEBASE_OAUTH2_TOKEN_PARAMS

Microsoft Entra ID example configuration:

TIMEBASE_URL=dxtick://example.com:8011
TIMEBASE_OAUTH2_TOKEN_URL=https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
TIMEBASE_OAUTH2_CLIENT_ID=<client-id>
TIMEBASE_OAUTH2_CLIENT_SECRET=<client-secret>
TIMEBASE_OAUTH2_SCOPE=api://example-api/.default

Use TIMEBASE_OAUTH2_TOKEN_PARAMS only if your provider requires extra token fields such as audience, resource, etc. It must be a valid JSON object.

Features

Tools

Name	Description	Key inputs	Notes
list_streams	List available TimeBase streams with descriptions	None	Read-only stream catalog lookup
get_stream_schema	Get the schema of a specific stream	stream_key	Returns the schema text for the requested stream
get_stream_time_range	Get the UTC time range of a specific stream	stream_key	Returns start and end timestamps
get_stream_symbols	Get symbols from a specific stream	stream_key, optional limit, optional cursor	Returns sorted, paginated symbols. limit can be 1-500
get_stream_messages	Preview the first or last messages from a stream	stream_key, optional reverse, optional count	Returns up to count JSON-formatted messages. Use reverse to read from the end of the stream
execute_query	Execute a TimeBase QQL query	query, optional limit	Returns a limited preview of result rows. limit can be 1-100
compile_query	Compile a TimeBase QQL query	query	Returns parser-level diagnostics only (not full semantic/logical validation). error_token is the first unexpected token, which may be after the actual root cause.

Resources

Some clients (e.g. VS Code) allow users to explicitly add resources to the context.

URI	Name	Description
timebase://streams	stream_catalog	Text resource listing streams and descriptions
timebase://streams/{stream_key}/schema	stream_schema	Resource template exposing a stream schema by key

Troubleshooting

General

• Green indicator in Cursor's MCP panel means the timebase-mcp server is running and Cursor is connected to it, but it doesn't necessarily mean that timebase-mcp is successfully connected to TimeBase.

Where to find logs?

VS Code

Logs can be found in the output panel (View > Output, then select timebase-mcp from the dropdown).

Cursor

Logs can be found in the Cursor's output panel (View > Output, then select timebase-mcp from the dropdown).

Claude Desktop

Logs can be found at Settings > Developer > TimeBase MCP > View Logs.

Claude Code

Launch Claude Code in an MCP debug mode:

claude --debug mcp

Refer to the official documentation for more details.

Opencode

MCP server logs can be found in the Opencode's log:

• On Linux and MacOS: ~/.local/share/opencode/log/
• On Windows: Press WIN+R and paste %USERPROFILE%\.local\share\opencode\log

Refer to the official documentation for more details.

Other

Logs are printed to stderr of the timebase-mcp process, look for them in the terminal where you started timebase-mcp or in the logs of your MCP client.

TimeBase connection issues

First, find the logs as described above and check for any error messages related to TimeBase connection. Common issues:

• TimeBase server is not running or not accessible from this environment (e.g. wrong URL, network issues, firewall, WSL misconfiguration, etc.). Look for messages like Connection refused at SOCKET.

• MCP edition mismatch: if you're trying to connect to TimeBase Enterprise but have the Community edition installed (or vice versa), you may see errors about protocol version mismatch and message about requiring an Enterprise/Community client.

• Remote access is not enabled: some features require remote access to be enabled on the TimeBase server. Refer to TimeBase documentation for instructions on how to enable it:

  • Remote Access for TimeBase Enterprise
  • Remote Access for TimeBase Community

• Missing DXAPI_SSL_TERMINATION flag: if your TimeBase server setup requires SSL termination, but the DXAPI_SSL_TERMINATION environment variable is not set to true, dxapi may hang indefinitely and you'll get MCP connection timeout errors in the logs.

For TimeBase CE make sure that both Native (usually 8011) and HTTP (usually 8021) ports are visible and exposed to MCP. For example in case of port forwarding:

kubectl port-forward pod/timebase-consolidated-0 8011:8011 8021:8021 -n dev-namespace

See also

TimeBase Agent Plugins