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

Tool	What it does	Quota impact
klinepic_get_capabilities	Checks API-key permissions, plan limits, remaining quota, and supported endpoints.	None
klinepic_preflight_review_chart	Validates fills, K-line data, scopes, and estimated cost before rendering.	None
klinepic_create_review_chart	Returns an annotated candlestick PNG as native MCP image content.	Uses one chart render

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

Local installation was last verified on 2026-07-14. Live API capabilities and preflight were last verified on 2026-07-13:

Check	Result	What was proved
API adapter tests	PASS — 4/4	Bearer authentication, forced review-chart mode, PNG-to-base64 conversion, and structured error handling.
Real MCP stdio handshake	PASS — 3 tools	A real MCP client completed initialization and discovered all three tool schemas.
Fresh Cline-compatible install	PASS — 3 tools	The Windows cmd /c npx configuration launched the GitHub package from an empty temporary directory and completed MCP initialization plus tool discovery.
One-click MCPB bundle	PASS — 3 tools	The official MCPB 0.3 validator accepted the manifest; the packed bundle included runtime dependencies and completed a real stdio handshake.
Live production capabilities	PASS	The MCP server called the production capability endpoint with a scoped Agent API key.
Live production preflight	PASS	The sample request passed production validation without rendering a chart or consuming chart quota.
Container build	PASS in CI	GitHub Actions builds the Docker image from a clean checkout.

Reproduce the local checks:

npm ci
npm test
npm run test:mcpb

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.

One-click install for MCPB-compatible desktop clients:

Download klinepic-mcp-server-0.1.0.mcpb, open it in the desktop client, and enter the Agent API key when prompted. The key field is marked sensitive. The API origin defaults to https://klinepic.com; change it only to a trusted HTTPS endpoint because the key and full trade payload are sent there.

Run directly from GitHub:

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

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#c48f3dc12a21834a2af165c223230f0cf9500fef"
      ],
      "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#c48f3dc12a21834a2af165c223230f0cf9500fef"
      ],
      "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

File	Use case
review-chart-request.json	Complete request for preflight or rendering
broker-trades-template.csv	Generic broker exports
binance-trade-history-template.csv	Binance trade history
us-stock-trading-journal-template.csv	US-stock journals
futures-trade-review-template.csv	Futures reviews
metatrader-trade-history-template.csv	MetaTrader 4/5 history

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

• Cline installation guide
• Standalone field guide
• Complete AI/GEO context bundle
• Human-readable Agent API guide
• OpenAPI contract
• GitHub Pages OpenAPI mirror
• Copy-paste quickstart
• Accepted one-click MCPB install and checksum Q&A
• Accepted official MCP Registry and OCI Q&A
• Claimed Glama listing and quality score
• MCP Repository directory listing
• Accepted MCP installation Q&A
• Accepted broker-fill workflow Q&A
• 中文 A 股交割单问答

Security and scope

• Report suspected vulnerabilities through the private security-reporting form, not a public issue.
• 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.