How do I install Vn Skills?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Vn Skills need an API key?

No required environment variable is listed on this record.

What transport does Vn Skills use?

Vn Skills runs locally over stdio.

When was Vn Skills last checked?

Last checked 2026-11-09. Vietnam: VietQR, address, tax ID, CCCD, phone, holiday, names, number/date format, lunar, e-invoice

Vn Skills MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @vn-skills/[email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.beiryu-vn-skills -- npx -y @vn-skills/mcp@0.8.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.beiryu-vn-skills": {4      "command": "npx",5      "args": [6        "-y",7        "@vn-skills/[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.8.0
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

vn-skills

Teach your AI agent to work with VietQR, e-invoices, the new 34-province addresses and more — with one command.

Tiếng Việt · 5-minute quickstart

Coding agents (Claude Code, Codex, Cursor, …) get Vietnam-specific tasks wrong: they invent bank BINs, use the pre-2025 provinces and districts, misread amounts in words, or confuse the Chinese and Vietnamese lunar calendars. vn-skills fixes that with three layers built on one offline core:

Layer	What	Install
Agent Skills	`skills/*/SKILL.md` following the Agent Skills spec	copy a folder into your agent's skills directory
CLI	`@vn-skills/cli` — `npx -y @vn-skills/cli …` (JSON output for agents)	nothing; the skills call it
MCP server	`@vn-skills/mcp` — the same functions as MCP tools	`claude mcp add vn-skills -- npx -y @vn-skills/mcp`
Library	`@vn-skills/core` — pure TypeScript, no network, data bundled	`npm i @vn-skills/core`

What it is: an offline toolkit. No accounts or API keys; it builds, parses and validates VietQR payloads and images. What it is not: a payment gateway. It does not collect payments or confirm transfers, and never calls bank or NAPAS APIs; pair it with a payment gateway for that.

Skills

Skill	Does	Example
`vietqr`	Build/parse VietQR (NAPAS 247, EMVCo) payloads, CRC16, PNG/SVG, bank BIN lookup	`vn-skills vietqr build --bank VCB --account 0011001234567 --amount 500000 --note "don 123" --out qr.png`
`vn-address`	Parse/normalise addresses; convert 63-province + district addresses to the 34-province, 2-level structure (01/07/2025)	`vn-skills address convert "P. Bến Nghé, Q.1, TP.HCM"` → `Phường Sài Gòn, Thành phố Hồ Chí Minh`
`vn-tax-id`	Validate tax IDs (10 / 13 digits, check digit, branch suffix; 12-digit personal ID) offline	`vn-skills taxid validate 0100233488-001`
`vn-id`	Validate/decode 12-digit CCCD (province, sex, birth year) and check 9-digit CMND format offline	`vn-skills id parse 048090123456`
`vn-phone`	Normalise phone numbers (+84, old 11-digit prefixes), carrier by prefix, landline area codes	`vn-skills phone 0912345678`
`vn-holidays`	Official days off per year (announced notices, nghỉ bù, swaps), working-day check and add N working days	`vn-skills holidays add 2026-02-12 3`
`vn-money-words`	Amount → Vietnamese words (nghìn/ngàn, lẻ/linh, mốt/lăm/tư, tỷ tỷ)	`vn-skills money words 1200000` → `một triệu hai trăm nghìn đồng`

Bulk-convert stored addresses (one per line → NDJSON, or a CSV column; exit code 2 if some rows fail):

vn-skills address convert-file addresses.txt
vn-skills address convert-file customers.csv --csv --column address > converted.csv
vn-skills address convert-file customers.csv --csv --province-column province --district-column district --ward-column ward > converted.csv

Install the skills

Claude Code plugin (all skills + the MCP server, one command):

/plugin marketplace add beiryu/vn-skills
/plugin install vn-skills@vn-skills

Claude Code (project or user scope):

git clone https://github.com/beiryu/vn-skills
cp -r vn-skills/skills/vietqr ~/.claude/skills/          # or .claude/skills/ inside your project

Then ask: "tạo QR chuyển 500k vào VCB số tài khoản 0011001234567" → Claude runs the skill and returns qr.png.

Or use the CLI (skills are bundled in the package):

npx -y @vn-skills/cli install vietqr --agent claude            # .claude/skills/vietqr (project)
npx -y @vn-skills/cli install all --agent cursor --global      # ~/.cursor/skills/*

--agent is claude, cursor, codex, agents or copilot (.github/skills/, or ~/.copilot/skills/ with --global). Existing folders are not overwritten without --force; --dry-run prints the actions only.

Cursor / Codex / other agents: copy the same folders into the agent's skills directory (.cursor/skills/, .codex/skills/, or wherever your agent discovers SKILL.md). The skills only need Node.js 22+ because they call npx -y @vn-skills/cli. .agents/skills/ is read by Codex (docs), Cursor (docs), Gemini CLI (docs) and GitHub Copilot in VS Code, Copilot CLI and the cloud agent (docs); install there with --agent agents. For the Copilot cloud agent, install in project scope (--agent agents without --global), because the cloud agent does not load personal skills.

Inside this repository run node packages/cli/dist/index.js … instead of npx -y @vn-skills/cli … to get clean JSON. pnpm vn-skills … also works but adds wrapper output (the echoed command and [ELIFECYCLE] on failures).

MCP server

claude mcp add vn-skills -- npx -y @vn-skills/mcp

Setup for other clients is in MCP client setup. Or in any MCP client config:

{ "mcpServers": { "vn-skills": { "command": "npx", "args": ["-y", "@vn-skills/mcp"] } } }

The server exposes 34 tools, grouped by skill. All tools are declared read-only and offline (readOnlyHint: true, openWorldHint: false).

Skill	Tools
`vietqr`	`vietqr_build`, `vietqr_parse`, `vietqr_decode`, `vietqr_banks`
`vn-address`	`vn_address_parse`, `vn_address_convert`, `vn_address_convert_batch`, `vn_address_search_wards`, `vn_address_history`, `vn_address_provinces`, `vn_address_province`
`vn-tax-id`	`vn_tax_id_validate`, `vn_tax_id_check_digit`
`vn-id`	`vn_id_parse`
`vn-phone`	`vn_phone`
`vn-holidays`	`vn_holidays_year`, `vn_holidays_is_working_day`, `vn_holidays_add_working_days`, `vn_holidays_count_working_days`
`vn-money-words`	`vn_money_to_words`, `vn_money_parse`
`vn-lunar`	`vn_lunar_from_solar`, `vn_lunar_to_solar`, `vn_lunar_month`, `vn_lunar_holidays`, `vn_lunar_tet`, `vn_lunar_canchi`
`vn-einvoice`	`vn_einvoice_validate`, `vn_einvoice_totals`, `vn_einvoice_vat`, `vn_einvoice_mock_issue`, `vn_einvoice_example`
`vn-name`	`vn_name`
`vn-number-format`	`vn_number_format`

MCP Apps hosts (Claude, ChatGPT, VS Code, …) show VietQR results (built with image: true) as an inline VietQR card with bank, account, amount and copy buttons; other clients see the usual JSON and image.

When a client declares the MCP elicitation capability, the address converter asks the user to pick the new ward if the old ward was split, and reports chosenBy (user or default).

Prompts

The server also offers prompt templates, shown as / commands in clients that support MCP prompts: tao-vietqr, doi-dia-chi-moi, kiem-tra-mst, doc-cccd, so-tien-bang-chu, ngay-lam-viec, doi-am-duong, kiem-tra-hoa-don.

Resources

Read-only data that clients can attach without a tool call (all application/json):

MCP client setup

Requires Node.js 22+. Each client has its own file and shape; check the linked docs for the exact location.

Claude Code:

claude mcp add vn-skills -- npx -y @vn-skills/mcp

Claude Desktop — claude_desktop_config.json:

{ "mcpServers": { "vn-skills": { "command": "npx", "args": ["-y", "@vn-skills/mcp"] } } }

Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global), same mcpServers shape:

{ "mcpServers": { "vn-skills": { "command": "npx", "args": ["-y", "@vn-skills/mcp"] } } }

VS Code — .vscode/mcp.json (top-level servers, not mcpServers):

{
  "servers": {
    "vn-skills": { "type": "stdio", "command": "npx", "args": ["-y", "@vn-skills/mcp"] }
  }
}

Codex — ~/.codex/config.toml:

[mcp_servers.vn-skills]
command = "npx"
args = ["-y", "@vn-skills/mcp"]

Docker

Build the image from this repository (the server is offline and needs no env vars):

docker build -t vn-skills-mcp .

Then point your client at it (it runs docker run -i --rm vn-skills-mcp):

{
  "mcpServers": {
    "vn-skills": { "command": "docker", "args": ["run", "-i", "--rm", "vn-skills-mcp"] }
  }
}

Other clients: use the generic mcpServers block above. AI agents (e.g. Cline) can follow llms-install.md.

HTTP mode

For a shared or remote server, run the opt-in Streamable HTTP transport (stateless, POST /mcp):

npx -y @vn-skills/mcp --http --port 3000   # http://127.0.0.1:3000/mcp

It binds to 127.0.0.1 by default; use --host 0.0.0.0 to expose it (e.g. docker run -p 3000:3000 vn-skills-mcp --http --host 0.0.0.0). Requests with a non-localhost Origin header get 403 unless you pass --allow-origin <origin> (repeatable). Without --http the server uses stdio.

Library

import {
  buildVietQR,
  convertAddress,
  validateTaxId,
  moneyToWords,
  lunarInfo,
  computeTotals,
} from '@vn-skills/core';

buildVietQR({ bank: 'VCB', account: '0011001234567', amount: 500000, note: 'don 123' }).payload;
convertAddress('12 Nguyễn Huệ, P. Bến Nghé, Q.1, TP.HCM').new.formatted; // "12 Nguyễn Huệ, Phường Sài Gòn, Thành phố Hồ Chí Minh"
validateTaxId('0100233488-001').kind; // "branch"
moneyToWords(1_200_000).words; // "một triệu hai trăm nghìn đồng"
lunarInfo(29, 1, 2025).text; // "Mùng 1 tháng Giêng năm Ất Tỵ"

Every function returns { ok: true, ... } or { ok: false, error: { code, message, hint } } — no exceptions for bad input.

Google Sheets

packages/sheets (private, not on npm) builds Apps Script custom functions from @vn-skills/core: pnpm --filter ./packages/sheets build writes packages/sheets/dist/vn-skills.gs, vn-skills-lite.gs and appsscript.json.

In a Google Sheet open Extensions → Apps Script and paste the contents of one .gs file.
Set the time zone to Asia/Ho_Chi_Minh (Project Settings, or use the timeZone in appsscript.json).
Save and use the functions in cells. Each accepts one value or a range and returns the same shape; a bad cell returns the error text.

Function	Example
`VN_TIEN_CHU(amount, [thousand])`	`=VN_TIEN_CHU(A2)`, `=VN_TIEN_CHU(A2:A9, "ngàn")`
`VN_SO_THANH_CHU(number)`	`=VN_SO_THANH_CHU(A2)`
`VN_MST(taxId)`	`=VN_MST(A2:A9)` → TRUE/FALSE
`VN_AM_LICH(date)`	`=VN_AM_LICH(A2)` or `=VN_AM_LICH("29/01/2025")`
`VN_NGAY_LAM_VIEC(date)`	`=VN_NGAY_LAM_VIEC(A2)` → TRUE/FALSE
`VN_CONG_NGAY_LAM_VIEC(date, n)`	`=VN_CONG_NGAY_LAM_VIEC(A2, 5)` (yyyy-mm-dd text)
`VN_DIA_CHI_MOI(address)`	`=VN_DIA_CHI_MOI(A2)` (full bundle only)

Bundle sizes (as measured by the build): vn-skills.gs ≈ 2520 KiB (includes the address data), vn-skills-lite.gs ≈ 39 KiB (no address functions). If the full bundle is too large for your project, use the lite bundle.

Development

pnpm install && pnpm build && pnpm test
pnpm build-data          # refresh bundled datasets from pinned upstream commits (network)

Data sources, licenses and dates are listed in packages/core/data/SOURCES.md. See CONTRIBUTING.md.

Roadmap

Next up: a Python port and real e-invoice sandbox adapters. Full list with acceptance criteria: ROADMAP.md.

Community

Contributing · Governance · Code of Conduct · Security · Name & brand policy · Sponsor

Disclaimer

This project provides technical tooling only. It is not tax, legal or accounting advice, does not query or scrape any government system, and does not guarantee that a tax ID is registered or that an address is accepted by a carrier. Verify with the competent authority where it matters.

VietQR and NAPAS are trademarks of the National Payment Corporation of Vietnam (NAPAS); bank names belong to their owners. vn-skills is not affiliated with, endorsed by or certified by NAPAS, any bank or any Vietnamese authority.

License

MIT. Bundled data is derived from MIT-licensed community datasets (see SOURCES.md and their licences in THIRD_PARTY_NOTICES.md); the lunar calendar is an independent implementation of the formulas in Jean Meeus, Astronomical Algorithms.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Vn Skills?

Does Vn Skills need an API key?

What transport does Vn Skills use?

When was Vn Skills last checked?

Documentation

vn-skills

Skills

Install the skills

MCP server

Prompts

Resources

MCP client setup

Docker

HTTP mode

Library

Google Sheets

Development

Roadmap

Community

Disclaimer

License