BitPin MCP Server (bitpin-mcp)
An official Model Context Protocol (MCP) server for the BitPin Iranian Cryptocurrency Exchange API (docs.bitpin.ir), built with the official @modelcontextprotocol/typescript-sdk.
This MCP server connects AI assistants (Claude Desktop, Cursor, Antigravity IDE, Cline, Roo Code, etc.) directly to BitPin, allowing users to inspect market prices, monitor orderbooks, place and cancel trading orders, view wallet balances, and manage deposits and withdrawals in real time.
Key Features
- Standard MCP Protocol: Runs via
stdiotransport, compatible with all major MCP clients. - English AI Descriptions with Persian (فارسی) Input Support:
- Detailed, precise tool definitions and parameter descriptions written in English for maximum AI model accuracy.
- Full support for Persian inputs:
- Persian cryptocurrency and fiat names:
بیت کوین,تتر,اتریوم,ترون,دوج کوین,تومان,سولانا,نات کوین, etc. - Market pairs:
بیت کوین به تومان,تتر تومان,اتریوم تتر, etc. - Order sides:
خرید(buy),فروش(sell). - Order types:
محدود(limit),بازار/فوری(market),استاپ لیمیت(stop_limit),دوطرفه(oco). - Persian & Arabic numerals: Automatically normalizes
۰۱۲۳۴۵۶۷۸۹to standard numbers. - Order states:
فعال(active),بسته(closed),اولیه(initial).
- Persian cryptocurrency and fiat names:
- Auto-Authentication & Refresh: Automatically exchanges API Key & Secret Key for Bearer JWT tokens, handles token caching, and auto-refreshes tokens on 401 expiration.
- Zero Configuration Required for Public Market Data: Fetch prices, currencies, orderbooks, and recent trades without any API keys.
Quick Start (with npx)
You can run the server directly using npx:
npx -y bitpin-mcp
Configuration with MCP Clients
1. Claude Desktop
Add the following to your claude_desktop_config.json:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"bitpin": {
"command": "npx",
"args": ["-y", "bitpin-mcp"],
"env": {
"BITPIN_API_KEY": "YOUR_BITPIN_API_KEY",
"BITPIN_SECRET_KEY": "YOUR_BITPIN_SECRET_KEY"
}
}
}
}
Note: If you only need public market data (prices, tickers, orderbook), you can omit the
envblock.
2. Cursor (.cursor/mcp.json)
Add the server to .cursor/mcp.json in your project or global Cursor settings:
{
"mcpServers": {
"bitpin": {
"command": "npx",
"args": ["-y", "bitpin-mcp"],
"env": {
"BITPIN_API_KEY": "YOUR_BITPIN_API_KEY",
"BITPIN_SECRET_KEY": "YOUR_BITPIN_SECRET_KEY"
}
}
}
}
3. Antigravity IDE / Cline / Roo Code / VS Code
{
"bitpin": {
"command": "npx",
"args": ["-y", "bitpin-mcp"],
"env": {
"BITPIN_API_KEY": "YOUR_BITPIN_API_KEY",
"BITPIN_SECRET_KEY": "YOUR_BITPIN_SECRET_KEY"
}
}
}
Environment Variables
[!WARNING] IP Whitelisting & HTTP 403 Forbidden Notice: BitPin enforces strict IP whitelisting for all API tokens in their Token Manager. When creating your API key pair on BitPin, you must specify the exact IP addresses authorized to access the API. Calling authenticated tools from any IP that is not predefined in BitPin's Token Manager (for instance, when connected to a VPN, a dynamic mobile network, or an unregistered server) will immediately result in an
HTTP 403 Forbiddenerror. If you encounter HTTP 403 errors, check your current public IP (e.g. viacurl ifconfig.me) and add it to your API Key whitelist in the BitPin panel. Public market data tools do not require IP whitelisting.
Available Tools
1. Market Data (Public & Authenticated)
2. Orders & Trading
3. Wallet & Transfers
4. Authentication Management
Persian Input Examples (نمونههای ورودی فارسی)
The server automatically handles Persian names, words, and numbers:
// Query price of Bitcoin in Toman:
bitpin_get_tickers({ symbol: "بیت کوین به تومان" }); // Resolves to BTC_IRT
// Query Tether price:
bitpin_get_tickers({ symbol: "تتر" }); // Resolves to USDT_IRT
// Place a limit buy order:
bitpin_place_order({
symbol: "تتر به تومان", // USDT_IRT
side: "خرید", // buy
type: "محدود", // limit
price: "۵۸۵۰۰", // 58500
base_amount: "۱۰۰" // 100
});
// Filter active orders:
bitpin_get_orders({
symbol: "بیت کوین",
state: "فعال" // active
});
Local Development & Publishing
Build Locally
npm install
npm run build
Run Locally
npm start
# or development with live reload:
npm run dev
Publish to npm
npm login
npm publish --access public
Once published to npm, anyone can run it immediately with:
npx -y bitpin-mcp