KLinePic MCP Server and Agent API Examples

English | 简体中文 | 日本語 | 한국어

Turn broker or exchange fills into annotated candlestick review-chart PNGs. AI agents can discover capabilities, validate a request without spending chart quota, and render the finished chart through three MCP tools.

KLinePic is for post-trade review and visualization. It does not provide trading signals, price predictions, investment advice, or order execution.

What is included

The repository also includes:

• A working JavaScript stdio MCP server.
• A small Agent API client used by the MCP tools.
• Broker, Binance, US-stock, futures, and MetaTrader sample data.
• A complete review-chart request and a no-charge preflight example.
• Docker support, an OpenAPI mirror, and machine-readable discovery files.

Verified functionality

Last verified on 2026-07-13 against the current source and the live KLinePic API:

Reproduce the local checks:

npm ci
npm test

Run the live, no-charge check with your own key:

KLINE_AGENT_API_KEY=kline_agent_xxx npm run test:production-preflight

The live check calls capabilities and preflight only. It does not call the paid render tool.

Quick start

Requirements:

• Node.js 20 or newer.
• A KLinePic Agent API key. Create one from the account page; the free tier does not require a sales conversation.

Run directly from GitHub:

KLINE_AGENT_API_KEY=kline_agent_xxx \
  npx -y github:sher1096/klinepic-agent-api-examples

Or clone the repository:

git clone https://github.com/sher1096/klinepic-agent-api-examples.git
cd klinepic-agent-api-examples
npm ci
KLINE_AGENT_API_KEY=kline_agent_xxx npm start

MCP client configuration

Most macOS and Linux clients can run the GitHub package directly:

{
  "mcpServers": {
    "klinepic": {
      "command": "npx",
      "args": [
        "-y",
        "github:sher1096/klinepic-agent-api-examples"
      ],
      "env": {
        "KLINE_AGENT_API_KEY": "kline_agent_xxx"
      }
    }
  }
}

Some Windows clients need cmd.exe to resolve npx.cmd:

{
  "mcpServers": {
    "klinepic": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "github:sher1096/klinepic-agent-api-examples"
      ],
      "env": {
        "KLINE_AGENT_API_KEY": "kline_agent_xxx"
      }
    }
  }
}

Keep the key in the client environment or secret store. Do not commit it.

Docker

Run the published image:

docker run --rm -i \
  -e KLINE_AGENT_API_KEY=kline_agent_xxx \
  ghcr.io/sher1096/klinepic-mcp-server:0.1.0

Or build it locally:

docker build -t klinepic-mcp .
docker run --rm -i \
  -e KLINE_AGENT_API_KEY=kline_agent_xxx \
  klinepic-mcp

The container can start without a key so a registry can inspect its tool schemas. API calls still require a valid key.

Recommended agent flow

1. Call klinepic_get_capabilities.
2. Build a request from the user's fills and K-line data.
3. Call klinepic_preflight_review_chart.
4. Fix any validation or permission error.
5. Ask for confirmation before a quota-consuming render.
6. Call klinepic_create_review_chart and return the PNG.

Preflight first: it catches malformed CSV, unsupported sources, missing scopes, IP restrictions, plan state, and quota limits without rendering.

Sample data

Run the standalone no-charge example:

KLINE_AGENT_API_KEY=kline_agent_xxx node examples/preflight.mjs

Troubleshooting

• KLINE_AGENT_API_KEY is required — create a key and pass it through the MCP client's environment.
• HTTP 401 — the key is invalid or revoked.
• HTTP 402 — the account or key quota is exhausted; capabilities shows the relevant limit.
• HTTP 403 — the key lacks the required scope or its IP allowlist blocks the caller.
• HTTP 422 — the request data is invalid; run preflight and inspect the structured details.
• Windows cannot find npx — use the cmd /c npx configuration above.

Documentation and discovery

• Standalone field guide
• Human-readable Agent API guide
• OpenAPI contract
• GitHub Pages OpenAPI mirror
• Copy-paste quickstart
• Accepted MCP installation Q&A
• Accepted broker-fill workflow Q&A
• 中文 A 股交割单问答

Security and scope

• API keys are sent only to https://klinepic.com unless KLINEPIC_BASE_URL is explicitly overridden.
• The server does not store keys, trade records, or generated images locally.
• Use a dedicated key with the smallest useful scopes and limits.
• Review data-handling requirements before sending real trading records.

License

The MCP adapter and examples in this repository are available under the MIT License. The hosted KLinePic API is a separate service governed by its published terms and privacy policy.