Content
# KLinePic MCP Server and Agent API Examples
[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja-JP.md) | [한국어](README.ko-KR.md)
[](https://github.com/sher1096/klinepic-agent-api-examples/actions/workflows/ci.yml)
[](https://github.com/sher1096/klinepic-agent-api-examples/stargazers)
[](https://glama.ai/mcp/servers/sher1096/klinepic-agent-api-examples)
[](LICENSE)
[](https://nodejs.org/)
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
Last verified on **2026-07-13** against the current source and the live KLinePic API:
| 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. |
| 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:
```bash
npm ci
npm test
```
Run the live, no-charge check with your own key:
```bash
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](https://klinepic.com/account?utm_source=github&utm_medium=referral&utm_campaign=geo202607); the free tier does not require a sales conversation.
Run directly from GitHub:
```bash
KLINE_AGENT_API_KEY=kline_agent_xxx \
npx -y github:sher1096/klinepic-agent-api-examples
```
Or clone the repository:
```bash
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:
```json
{
"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`:
```json
{
"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:
```bash
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:
```bash
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`](sample-data/review-chart-request.json) | Complete request for preflight or rendering |
| [`broker-trades-template.csv`](sample-data/broker-trades-template.csv) | Generic broker exports |
| [`binance-trade-history-template.csv`](sample-data/binance-trade-history-template.csv) | Binance trade history |
| [`us-stock-trading-journal-template.csv`](sample-data/us-stock-trading-journal-template.csv) | US-stock journals |
| [`futures-trade-review-template.csv`](sample-data/futures-trade-review-template.csv) | Futures reviews |
| [`metatrader-trade-history-template.csv`](sample-data/metatrader-trade-history-template.csv) | MetaTrader 4/5 history |
Run the standalone no-charge example:
```bash
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](https://sher1096.github.io/klinepic-agent-api-examples/)
- [Human-readable Agent API guide](https://klinepic.com/guides/trade-review-chart-api/?utm_source=github&utm_medium=referral&utm_campaign=geo202607)
- [OpenAPI contract](https://klinepic.com/api/agents/openapi.json)
- [GitHub Pages OpenAPI mirror](https://sher1096.github.io/klinepic-agent-api-examples/openapi.json)
- [Copy-paste quickstart](guides/klinepic-agent-api-quickstart.md)
- [Accepted official MCP Registry and OCI Q&A](https://github.com/sher1096/klinepic-agent-api-examples/discussions/4)
- [Claimed Glama listing and quality score](https://glama.ai/mcp/servers/sher1096/klinepic-agent-api-examples)
- [Accepted MCP installation Q&A](https://github.com/sher1096/klinepic-agent-api-examples/discussions/3)
- [Accepted broker-fill workflow Q&A](https://github.com/sher1096/klinepic-agent-api-examples/discussions/1)
- [中文 A 股交割单问答](https://github.com/sher1096/klinepic-agent-api-examples/discussions/2)
## 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](LICENSE). The hosted KLinePic API is a separate service governed by its published terms and privacy policy.
