TimeBase — Claude Code MCP server: setup
This MCP server lets an AI coding agent inspect TimeBase streams, schemas, symbols, messages, QQL results, and server activity.
claude mcp add --env TIMEBASE_URL=<TIMEBASE_URL> --env TIMEBASE_SERVERS=<TIMEBASE_SERVERS> --env TIMEBASE_USERNAME=<TIMEBASE_USERNAME> --env TIMEBASE_PASSWORD=<TIMEBASE_PASSWORD> --env TIMEBASE_OAUTH2_TOKEN_URL=<TIMEBASE_OAUTH2_TOKEN_URL> --transport stdio timebase -- uvx timebase-mcpWhat TimeBase does
TimeBase connects an MCP-compatible coding agent with a TimeBase instance. The agent can enumerate streams, inspect schemas and symbols, sample messages, run QQL queries, and view server status and activity.
You can run timebase-mcp on the local machine over stdio, or deploy it as an HTTP service shared by several users. The local setup uses uvx to start the server.
A shared HTTP setup requires a separate server deployment. Connection settings include TIMEBASE_URL, TIMEBASE_SERVERS, TIMEBASE_USERNAME, TIMEBASE_PASSWORD, and TIMEBASE_OAUTH2_TOKEN_URL.
What it helps with
- list available TimeBase streams
- inspect a stream schema
- preview symbols and messages
- run a QQL query
- check server status
Example prompts for the agent
- List the TimeBase streams and show the schema for one of them.
- Preview messages from a selected stream and describe their fields.
- Run a QQL query against TimeBase and report the server status.
How to install TimeBase
Platform CLI
claude mcp add --env TIMEBASE_URL=<TIMEBASE_URL> --env TIMEBASE_SERVERS=<TIMEBASE_SERVERS> --env TIMEBASE_USERNAME=<TIMEBASE_USERNAME> --env TIMEBASE_PASSWORD=<TIMEBASE_PASSWORD> --env TIMEBASE_OAUTH2_TOKEN_URL=<TIMEBASE_OAUTH2_TOKEN_URL> --transport stdio timebase -- uvx timebase-mcpReplace <…> with your own values. 10 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from timebase-mcp <command>
Platform CLI
codex mcp add timebase --env TIMEBASE_URL=<TIMEBASE_URL> --env TIMEBASE_SERVERS=<TIMEBASE_SERVERS> --env TIMEBASE_USERNAME=<TIMEBASE_USERNAME> --env TIMEBASE_PASSWORD=<TIMEBASE_PASSWORD> --env TIMEBASE_OAUTH2_TOKEN_URL=<TIMEBASE_OAUTH2_TOKEN_URL> -- uvx timebase-mcpReplace <…> with your own values. 10 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from timebase-mcp <command>
Config file
{
"mcpServers": {
"timebase": {
"command": "uvx",
"args": [
"timebase-mcp"
],
"env": {
"TIMEBASE_URL": "<TIMEBASE_URL>",
"TIMEBASE_SERVERS": "<TIMEBASE_SERVERS>",
"TIMEBASE_USERNAME": "<TIMEBASE_USERNAME>",
"TIMEBASE_PASSWORD": "<TIMEBASE_PASSWORD>",
"TIMEBASE_OAUTH2_TOKEN_URL": "<TIMEBASE_OAUTH2_TOKEN_URL>"
}
}
}
}Replace <…> with your own values. 10 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from timebase-mcp <command>
Config file
{
"servers": {
"timebase": {
"type": "stdio",
"command": "uvx",
"args": [
"timebase-mcp"
],
"env": {
"TIMEBASE_URL": "<TIMEBASE_URL>",
"TIMEBASE_SERVERS": "<TIMEBASE_SERVERS>",
"TIMEBASE_USERNAME": "<TIMEBASE_USERNAME>",
"TIMEBASE_PASSWORD": "<TIMEBASE_PASSWORD>",
"TIMEBASE_OAUTH2_TOKEN_URL": "<TIMEBASE_OAUTH2_TOKEN_URL>"
}
}
}
}Replace <…> with your own values. 10 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from timebase-mcp <command>
Platform CLI
gemini mcp add -e TIMEBASE_URL=<TIMEBASE_URL> -e TIMEBASE_SERVERS=<TIMEBASE_SERVERS> -e TIMEBASE_USERNAME=<TIMEBASE_USERNAME> -e TIMEBASE_PASSWORD=<TIMEBASE_PASSWORD> -e TIMEBASE_OAUTH2_TOKEN_URL=<TIMEBASE_OAUTH2_TOKEN_URL> timebase uvx timebase-mcpReplace <…> with your own values. 10 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from timebase-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about TimeBase
How do I install TimeBase in Claude Code?
Run `claude mcp add timebase-mcp -e TIMEBASE_PASSWORD=<TIMEBASE_PASSWORD> -e TIMEBASE_OAUTH2_CLIENT_SECRET=<TIMEBASE_OAUTH2_CLIENT_SECRET> -- uvx timebase-mcp`.
What does TimeBase do?
It gives an MCP-compatible coding agent tools for browsing TimeBase streams, reading schemas and symbols, previewing messages, running QQL, and checking server activity.
Can TimeBase use a shared remote server?
Yes. Deploy timebase-mcp as an HTTP service, then connect multiple users and their agents to that service.
