TickDB MCP

tickdb-mcp connects AI assistants to the TickDB API through the Model Context Protocol. It provides 43 tools for market data, company fundamentals, and API Key subscriptions.

The package supports Python 3.11+, local stdio, and Streamable HTTP. Each tool makes a request to the TickDB REST API; this server does not provide WebSocket streaming subscriptions. Data availability and quotas depend on the API Key's subscription and permissions.

Install

Create a virtual environment and install version 0.2.4 from PyPI:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install tickdb-mcp==0.2.4

Obtain a TickDB API Key from tickdb.ai. Every value beginning with YOUR_ below is a placeholder; replace it locally and keep real credentials out of source control and chat messages.

Local stdio

Configure your MCP client to launch tickdb-mcp with MCP_TRANSPORT=stdio and your API Key in TICKDB_API_KEY. The equivalent Bash command is:

MCP_TRANSPORT=stdio TICKDB_API_KEY=YOUR_TICKDB_API_KEY tickdb-mcp

The client communicates with the process through stdin/stdout. Stdio does not start an HTTP listener or require an MCP access token. Logs go to stderr so they do not mix with protocol messages.

HTTP with each caller's own Key

With no environment overrides or .env configuration, start the server:

tickdb-mcp

It listens only on 127.0.0.1:8000. Connect your HTTP MCP client to http://127.0.0.1:8000/mcp and send X-TickDB-Key: YOUR_TICKDB_API_KEY on each request. For example, initialize the connection with:

curl --fail-with-body http://127.0.0.1:8000/mcp \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -H 'X-TickDB-Key: YOUR_TICKDB_API_KEY' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"example","version":"1"}}}'

When both the server Key and access token are empty, anonymous initialization and tool discovery are available, but data queries still need the caller's Key. A successful initialization alone does not prove that a Key is valid or entitled to market data.

HTTP with a shared server Key

To let approved clients use a server-wide TickDB Key, configure both credentials:

TICKDB_API_KEY=YOUR_TICKDB_API_KEY \
MCP_ACCESS_TOKEN=YOUR_RANDOM_MCP_ACCESS_TOKEN \
tickdb-mcp

TICKDB_API_KEY authenticates the server's requests to TickDB. MCP_ACCESS_TOKEN is a separate, strong random access credential for this MCP server. Clients must send Authorization: Bearer YOUR_RANDOM_MCP_ACCESS_TOKEN on every legacy HTTP request, including requests that also supply their own X-TickDB-Key. After that authentication succeeds, the request's own Key takes priority over the shared server Key.

If a shared server Key is configured without an access token, legacy HTTP requests without their own Key return 401, including initialization, discovery, and tool calls. This protection also applies on localhost and behind a reverse proxy. Clients may still supply their own Key when no access token is configured.

Configuration and public hosting

Settings come from environment variables or a .env file in the working directory. Existing .env files are not rewritten during upgrades. Important settings include:

Expose HTTP deliberately, use HTTPS for remote connections, and protect access to credentials. A private network, proxy, or Host header check does not replace authentication. The source Dockerfile explicitly listens on 0.0.0.0 inside the container; bind the published host port to 127.0.0.1 for local clients or a same-host reverse proxy. See the self-hosting guide for Docker and HTTPS configuration.

Optional OAuth

Self-hosted OAuth requires explicit configuration, public HTTPS, an exact callback allowlist, and persistent encrypted authorization storage. The separate /oauth endpoint uses the API Key that the user verified and explicitly authorized. It does not accept X-TickDB-Key overrides or fall back to a shared server Key. Enabling OAuth does not automatically protect the legacy /mcp endpoint; the rules above still apply to that endpoint.

Retain existing OAuth configuration, encryption keys, databases, and valid grants during upgrades. Follow the OAuth setup guide before enabling this mode.

Tool capabilities

Market data covers forex, precious metals, indices, US/HK/A-share stocks, China/Hong Kong futures, and cryptocurrencies. Company fundamentals cover supported US, Hong Kong, and A-share stocks. Results preserve upstream response envelopes; missing or null fields are not zero. Returned news is external content, not instructions.

Documentation and support

• English MCP guide
• 简体中文 · 繁體中文
• MCP client setup
• TickDB API documentation
• Source code · Issues

License

MIT. See the license text.