Konseki

Official Model Context Protocol server for Konseki.

Konseki is a pre-computed historical market context API for global equities, built for AI trading and quants. It matches current market conditions against historical analogs and returns structured pattern-match data, outcome distributions, and match-quality scores, grounding an AI agent's reasoning in evidence rather than generic commentary.

Konseki MCP is a direct wrapper around the Konseki public API. It lets AI agents and AI trading tools call Konseki endpoints through MCP tools while preserving the raw API response JSON for the user or downstream application to interpret.

Published package: @konseki/mcp

Requirements

• Node.js 20 or newer.
• A Konseki API key.

Get an API key from konseki.io.

Design Principles

• Direct API wrapper: the MCP server fetches Konseki API responses and returns them without interpretation.
• User-owned interpretation: users, builders, and downstream AI clients decide how to analyze or summarize the returned JSON.
• Public API only: the server uses X-API-Key against documented Konseki endpoints.
• No internal credentials: non-public service or operational credentials are never required for this package.

Configuration

The server reads configuration from environment variables:

KONSEKI_API_KEY=ks_live_your_api_key

Do not commit real API keys.

Intended Architecture

AI client
  |
  v
Konseki MCP server
  |
  v
Konseki public API
  |
  v
Raw historical market context JSON

The MCP server should not bypass Konseki public API behavior. It should behave like any other public API client.

Tools

get_konseki_metadata

Fetches raw JSON from GET /v1/metadata?country={country}.

Input:

{
  "country": "US"
}

list_konseki_countries

Fetches raw JSON from GET /v1/countries.

Input: none.

list_konseki_symbols

Fetches raw JSON from GET /v1/symbols?country={country}.

Input:

{
  "country": "US"
}

get_konseki_analysis

Fetches raw JSON from GET /v1/analysis/{symbol}-{exchange}?country={country}&lookback={lookback}.

Input:

{
  "country": "US",
  "symbol": "AAPL",
  "exchange": "NASDAQ",
  "lookback": 15
}

Supported lookback values: 5, 10, 15, 20, 25, 30, 40, 50.

Response Compression

The server requests gzip-compressed API responses and decompresses them locally before returning JSON to the MCP client. This is handled automatically; users do not need to configure compression.

Installation

Use the published npm package through an MCP client with npx:

{
  "mcpServers": {
    "konseki": {
      "command": "npx",
      "args": ["-y", "@konseki/mcp"],
      "env": {
        "KONSEKI_API_KEY": "ks_live_your_api_key"
      }
    }
  }
}

This is the recommended configuration for users who want the official released package from npm.

Local Development

For development from this checkout, install dependencies, build the package, and configure your MCP client to run the built server:

npm install
npm run build

{
  "mcpServers": {
    "konseki": {
      "command": "node",
      "args": ["/absolute/path/to/konseki-mcp/dist/index.js"],
      "env": {
        "KONSEKI_API_KEY": "ks_live_your_api_key"
      }
    }
  }
}

Development

Install dependencies:

npm install

Run verification:

npm run typecheck
npm test
npm run build

Security

• Never commit real API keys.
• Never log raw API keys.
• Never include user credentials in test snapshots or examples.
• Use fake keys in documentation and tests.