Content
# Chartink MCP Server
An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets Claude — or any MCP-compatible AI agent — run **[Chartink](https://chartink.com) stock screeners and backtests** for the Indian (NSE/BSE) market directly from a chat.
You describe a strategy in plain English, the agent writes the Chartink **scan clause**, and this server runs it against Chartink and returns the matching stocks.
> Bundled with a **`chartink-query` skill** (see [`skills/`](skills/)) that teaches the agent the full Chartink scan-clause syntax — every indicator, function, and gotcha — so it writes correct queries on the first try.
---
## Features
| Tool | What it does |
|------|--------------|
| `set_cookies` | Authenticate using your Chartink browser session cookies. |
| `run_screener` | Run a scan clause and return matching stocks (`/screener/process`). |
| `run_multiple_screeners` | Run several scan clauses in one call (compare strategies). |
| `run_backtest` | Run a scan clause through Chartink's `/backtest/process` endpoint. |
| `run_saved_screener` | Fetch a public saved screener by its URL slug and run it. |
---
## Requirements
- **Python 3.10+** (developed on 3.11) — required by the `mcp` package; your system's default `python3` may be older, see [Installation](#installation)
- A **Chartink account** (free works for most scans; some features need premium)
- An MCP-compatible client: **Claude Desktop**, **Claude Code**, or any agent that speaks MCP over stdio
---
## Installation
> ⚠️ **Check your Python version first.** The `mcp` package requires **Python 3.10+**. On many machines the default `python3` is older (e.g. macOS ships 3.9), and `pip install mcp` will fail with a dependency/`SyntaxError`. Verify:
> ```bash
> python3 --version # must be 3.10 or newer
> ```
> If it's older, use one of the options below to get a 3.10+ interpreter.
```bash
# 1. Clone
git clone https://github.com/<your-username>/chartink-mcp.git
cd chartink-mcp
```
### Option A — using `uv` (recommended; handles the Python version for you)
[`uv`](https://docs.astral.sh/uv/) auto-downloads a suitable Python, so you don't need a system 3.10+:
```bash
uv venv venv --python 3.11 # creates ./venv with Python 3.11
uv pip install --python venv/bin/python -r requirements.txt
```
### Option B — plain `venv` + `pip`
```bash
# Use a 3.10+ interpreter. If `python3` is too old, call a specific one,
# e.g. python3.11 / python3.12 (install via Homebrew: `brew install python@3.11`).
python3.11 -m venv venv # or: python3 -m venv venv (only if 3.10+)
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
```
Dependencies (`requirements.txt`): `mcp`, `requests`, `beautifulsoup4`.
**Verify the install:**
```bash
venv/bin/python --version # should print 3.10+
venv/bin/python -c "import server; print('OK')" # deps load, server importable
```
Note the **absolute path** to the venv's Python and to `server.py` — you'll need them for the client config:
```bash
echo "$(pwd)/venv/bin/python" # → command
echo "$(pwd)/server.py" # → args[0]
```
---
## Configuration
The server runs over **stdio**. Point your MCP client at the venv Python + `server.py`. Ready-to-edit templates live in [`config-examples/`](config-examples/).
### Claude Desktop
Edit the config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"chartink": {
"command": "/absolute/path/to/chartink-mcp/venv/bin/python",
"args": ["/absolute/path/to/chartink-mcp/server.py"]
}
}
}
```
Restart Claude Desktop. You should see the `chartink` tools appear.
### Claude Code
Create (or edit) `.mcp.json` in your project root:
```json
{
"mcpServers": {
"chartink": {
"command": "/absolute/path/to/chartink-mcp/venv/bin/python",
"args": ["/absolute/path/to/chartink-mcp/server.py"]
}
}
}
```
Or add it via the CLI:
```bash
claude mcp add chartink -- /absolute/path/to/chartink-mcp/venv/bin/python /absolute/path/to/chartink-mcp/server.py
```
### Any other MCP client
Use the generic stdio form — run the command below and speak MCP to its stdin/stdout:
```
/absolute/path/to/chartink-mcp/venv/bin/python /absolute/path/to/chartink-mcp/server.py
```
---
## Authentication (one-time per session)
Chartink's scan endpoints need a valid session, so you pass it your browser cookies once.
1. Log in to **[chartink.com](https://chartink.com)** in Chrome.
2. Open **DevTools → Network** tab.
3. Click any request to `chartink.com`, go to **Headers → Request Headers**, and copy the **entire `Cookie:` value** (it contains `XSRF-TOKEN=...; ci_session=...; ...`).
4. In your AI chat, tell the agent to set the cookies, e.g.:
> "Set my Chartink cookies: `XSRF-TOKEN=...; ci_session=...; ...`"
(This calls `set_cookies`.) You'll get back **"XSRF-TOKEN found ✓"** if it worked.
Cookies live for the duration of the server process. Re-run `set_cookies` if requests start failing (session expired).
> ⚠️ **Never commit your cookies.** They are credentials. The `.gitignore` already excludes common secret/cache files, but treat the cookie string like a password.
---
## Usage examples
Once configured and authenticated, just talk to the agent:
> "Find NSE stocks within 5% of their 52-week high with rising volume."
> "Run this scan clause and show me the matches:
> `( {cash} ( latest rsi( 14 ) > 60 and latest close > latest sma( latest close , 50 ) ) )`"
> "Run the saved screener `short-term-breakouts`."
> "Compare two strategies: an RSI breakout vs a MACD crossover."
The agent writes the scan clause (using the bundled skill), the server runs it, and you get the stock list back.
### Scan-clause shape (quick primer)
```
( {cash} ( <condition> [and|or <condition>] ... ) )
```
`{cash}` = all NSE cash stocks. Conditions use Chartink's English-like grammar, e.g.
`latest close > latest sma( latest close , 50 )`. See the bundled **skill** for the full syntax.
---
## The `chartink-query` skill
The [`skills/chartink-query/`](skills/chartink-query/) folder is a portable **Claude skill** that documents the entire Chartink scan-clause language — price/volume attributes, timeframes & candle offsets, every indicator (SMA, EMA, RSI, MACD, ADX, Bollinger, Stochastic, Supertrend, Donchian, VWAP, OBV, pivots…), functions (`max`/`min`/`count`/`abs`), crossover construction, segments, and the supported fundamental fields — plus a library of ready-to-use example queries.
With the skill installed, the agent writes **valid scan clauses on the first try** and can produce both the MCP/API form and the copy-paste form for chartink.com.
### Install the skill
**Claude Code** — copy it into either location:
```bash
# user-level (available in every project)
cp -r skills/chartink-query ~/.claude/skills/
# or project-level
mkdir -p .claude/skills && cp -r skills/chartink-query .claude/skills/
```
**Claude Desktop / other agents** — point your skills directory at `skills/chartink-query/`, or paste the contents of `SKILL.md` into your system prompt / project knowledge.
Then just ask: *"write a chartink query for stocks breaking a 20-day high with a volume surge"* and the skill handles the syntax.
---
## Project structure
```
chartink-mcp/
├── server.py # the MCP server
├── requirements.txt
├── README.md
├── LICENSE
└── skills/
└── chartink-query/ # portable Claude skill for Chartink syntax
├── SKILL.md
├── reference.md # full keyword/indicator/function catalog
└── examples.md # ready-to-use query patterns
```
---
## Troubleshooting
| Symptom | Fix |
|---------|-----|
| `pip install` fails on `mcp` / `SyntaxError` during install | Your Python is < 3.10. Build the venv with a 3.10+ interpreter (`python3.11 -m venv venv`) or use the `uv` option in [Installation](#installation). |
| Tools don't appear in the client | Check the absolute paths in the config; restart the client (Claude Desktop must be fully quit & reopened). |
| `XSRF-TOKEN not found` / `are you logged in?` | Re-run `set_cookies` with a fresh cookie string from a logged-in browser. |
| Requests suddenly fail | Session expired — set cookies again. |
| `run_saved_screener` says "Could not extract scan_clause" | That scan is **private** (its clause isn't in the public page). Ask the owner for the clause and use `run_screener` instead. |
| `run_backtest` returns empty | Chartink's full target/stop backtest is a website/premium feature; the endpoint may not return rich data via API. Use the website's Backtest tab for performance stats. |
---
## Disclaimer
This project is for **educational and research purposes only**. It is **not investment advice**, and the authors are not SEBI-registered advisers. Screener output and any backtests are **not** recommendations to buy or sell. Always do your own due diligence and manage your own risk. Use in accordance with Chartink's terms of service.
---
## Contributing
Issues and PRs welcome. Ideas: caching, richer backtest parsing, more example skills, tests.
## License
[MIT](LICENSE)
