CodeQR MCP server
2026년 10월 24일 커밋AI 클라이언트를 통해 단축 링크, 동적 QR 코드 생성 및 클릭 분석을 관리합니다.
다른 이름 codeqr-io/codeqr-mcp-remote, codeqr-mcp-remote
- 스타
- 0
- Tools
- 14
- 다운로드, 30일
- —
- 최신 버전
- 0.1.0
- 마지막 커밋
- 2026년 10월 24일
- 라이선스
- —
CodeQR MCP란?
AI 클라이언트를 통해 단축 링크, 동적 QR 코드 생성 및 클릭 분석을 관리합니다. 14개 도구를 제공합니다. 예: create_link, list_links, get_link_info.
프로젝트 README에서 생성된 요약
CodeQR MCP server 정보
CodeQR를 사용하면 AI 클라이언트에서 직접 단축 링크, 동적 QR 코드 및 클릭 분석을 관리할 수 있습니다. 이 원격 MCP server를 통해 개발자는 create_link, create_qrcode, get_analytics와 같은 도구로 CodeQR API와 상호작용할 수 있습니다. ChatGPT, OpenAI Agents SDK, Grok 및 streamable HTTP 전송을 지원하는 모든 클라이언트에서 사용할 수 있도록 설계되었습니다.
보안은 OAuth 2.0 인증을 통해 처리되므로 사용자가 API key를 수동으로 관리할 필요가 없습니다. 대신 클라이언트의 동의 화면에서 특정 프로젝트를 선택하여 액세스 권한을 부여합니다. 서버는 투명하게 갱신되는 장기 세션을 지원하여 연결이 최대 1년 동안 유지되도록 합니다. Vercel과 같은 플랫폼에서 프로덕션 배포를 하는 경우, 서버리스 호출 간에 인증 코드와 토큰을 유지하기 위해 Upstash Redis를 사용하는 것을 권장합니다.
단순한 생성을 넘어, 조건부 라우팅을 위한 스마트 규칙 및 A/B 테스트를 위한 트래픽 분할과 같은 고급 기능을 지원합니다. 호스트가 MCP Apps를 지원하는 경우, 사용자는 채팅 인터페이스 내에서 대화형 아이템 카드와 분석 대시보드를 직접 확인할 수 있습니다.
활용 사례
- 1동적 QR 코드 생성URL, Wi-Fi 정보, 연락처 카드 또는 암호화폐 요청을 포함하는 QR 코드를 생성합니다.
- 2A/B 테스트 수행스마트 규칙을 사용하여 여러 목적지로 트래픽을 분할합니다.
- 3링크 성능 모니터링클릭 분석을 조회하여 단축 링크와 QR 코드의 성과를 확인합니다.
- 4기존 자산 관리물리적인 코드를 다시 인쇄할 필요 없이 QR 코드의 목적지를 업데이트합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
CodeQR MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 CodeQR MCP 설치
$ claude mcp add --transport http codeqr-mcp-remote https://mcp.codeqr.io/mcpCursor에 CodeQR MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"codeqr-mcp-remote": {
"url": "https://mcp.codeqr.io/mcp"
}
}
}VS Code에 CodeQR MCP 설치
.vscode/mcp.json
{
"servers": {
"codeqr-mcp-remote": {
"type": "http",
"url": "https://mcp.codeqr.io/mcp"
}
}
}VS Code CLI에 CodeQR MCP 설치
$ code --add-mcp '{"name":"codeqr-mcp-remote","type":"http","url":"https://mcp.codeqr.io/mcp"}'Codex에 CodeQR MCP 설치
$ codex mcp add codeqr-mcp-remote --url https://mcp.codeqr.io/mcpCodex config.toml에 CodeQR MCP 설치
~/.codex/config.toml
[mcp_servers.codeqr-mcp-remote] url = "https://mcp.codeqr.io/mcp"
Gemini CLI에 CodeQR MCP 설치
$ gemini mcp add -s user --transport http codeqr-mcp-remote https://mcp.codeqr.io/mcpGemini settings.json에 CodeQR MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"codeqr-mcp-remote": {
"url": "https://mcp.codeqr.io/mcp",
"type": "http"
}
}
}CodeQR MCP 도구 14
README에서 감지됨create_linklist_linksget_link_infoupdate_linkdelete_linkcreate_qrcodelist_qrcodesupdate_qrcodedelete_qrcodeget_analyticslist_domainslist_tags
| create_link | — | |
| list_links | — | |
| get_link_info | — | |
| update_link | — | |
| delete_link | — | |
| create_qrcode | — | |
| list_qrcodes | — | |
| update_qrcode | — | |
| delete_qrcode | — | |
| get_analytics | — | |
| list_domains | — | |
| list_tags | — |
도구 14개 모두 보기도구 수 줄이기
create_tagget_workspace
| create_tag | — | |
| get_workspace | — |
구성
PRIVATE_KEY
| 이름 | 설명 | 유형 |
|---|---|---|
| PRIVATE_KEY | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능codeqr-io/codeqr-mcp-remote is public and reachablegithub.com/codeqr-io/codeqr-mcp-remote ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)No license결함 발견
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-24github.com/codeqr-io/codeqr-mcp-remote ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음14 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답HTTPS endpoint answered 401 (sign-in required)통과
README
GitHub에서 보기CodeQR Remote MCP Server
Remote MCP server for CodeQR with OAuth 2.0 authentication. Compatible with ChatGPT, OpenAI Agents SDK, Grok (xAI), and any MCP client supporting Streamable HTTP transport.
How It Works
┌──────────┐ ┌─────────────────────┐ ┌──────────┐
│ ChatGPT │ │ CodeQR MCP Remote │ │ CodeQR │
│ or any │─────▶│ │─────▶│ API │
│ MCP │◀─────│ OAuth 2.0 + MCP │◀─────│ │
│ client │ │ Streamable HTTP │ │ │
└──────────┘ └─────────────────────┘ └──────────┘
- Client discovers auth endpoints via
/.well-known/oauth-protected-resource - Client registers dynamically via
POST /oauth/register GET /oauth/authorizeshows this server's consent screen — the app's self-declared name, marked unverified unless its exact redirect URI is listed insrc/oauth/verified-clients.ts, and the host that redirect URI points at. On approval the user goes to CodeQR, where they log in, choose which project to grant access to, and approve — no API key is ever handled. The callback only completes in the browser that approved.- CodeQR returns them to
GET /oauth/callback, which trades the code for an access + refresh token pair - Client exchanges authorization code for access token (PKCE)
- Client sends MCP tool calls with Bearer token to
POST /mcp
The CodeQR access token lasts 7 days and is renewed transparently. Each
renewal gives the session another 120 days, so a connection in use does not
expire on a fixed date; an idle one ends 120 days after its last renewal, and
none outlives one year from when it was made (the expires_in the client is
given).
Quick Start
# Install dependencies
npm install
# Set environment variables
cp .env.example .env
# Edit .env with your SERVER_URL
# Development
npm run dev
# Production
npm run build
npm start
Deploy
Vercel (Recommended)
The project is configured for Vercel serverless functions:
# Install Vercel CLI
npm i -g vercel
# Deploy
vercel
# Set environment variables in Vercel dashboard:
# - SERVER_URL — Your public server URL (e.g., https://mcp.codeqr.io)
# - UPSTASH_REDIS_REST_URL — From your Upstash Redis database (REST API)
# - UPSTASH_REDIS_REST_TOKEN — From your Upstash Redis database
# - CODEQR_OAUTH_CLIENT_ID — client_id of the OAuth app registered in CodeQR
# - CODEQR_OAUTH_CLIENT_SECRET — its client_secret
# - CODEQR_APP_URL — Dashboard origin (default: https://app.codeqr.io)
# - MCP_UI_ENABLED — Set to 1 to show the item card in hosts that render MCP Apps (off when unset)
# - STAINLESS_API_KEY — Optional Stainless API key
# - LOG_LEVEL — Log level (default: info)
The app will be available at https://your-project.vercel.app. All routes are handled by the serverless function at api/server.ts.
OAuth storage: Set Upstash Redis (UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN) so authorization codes, access tokens, and registered clients persist across serverless invocations. If these variables are omitted, the server falls back to an in-memory store (fine for local development only).
Docker
docker build -t codeqr-mcp-remote .
docker run -p 3000:3000 -e SERVER_URL=https://mcp.codeqr.io codeqr-mcp-remote
Railway / Render / Fly.io
Set environment variables:
SERVER_URL— Your public server URL (e.g.,https://mcp.codeqr.io)UPSTASH_REDIS_REST_URL/UPSTASH_REDIS_REST_TOKEN— Recommended for multi-instance or restartsPORT— Port (usually set automatically by the platform)
Connect to ChatGPT
- Deploy this server to a public URL
- In ChatGPT, go to Settings > Advanced > Developer Mode
- Go to the Connectors tab
- Click Add Connector
- Enter your server URL (e.g.,
https://mcp.codeqr.io/mcp) - ChatGPT will auto-discover the OAuth endpoints and prompt you to authorize
Connect to OpenAI Agents SDK
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-4o",
tools=[{
"type": "mcp",
"server_label": "codeqr",
"server_url": "https://mcp.codeqr.io/mcp",
"require_approval": "never",
}],
input="Create a short link for https://codeqr.io",
)
Available Tools
| Tool | Description |
|---|---|
create_link |
Create a shortened link |
list_links |
List all short links |
get_link_info |
Get link details |
update_link |
Update a link |
delete_link |
Delete a link |
create_qrcode |
Create a dynamic QR code encoding a URL, Wi-Fi credentials, a contact card, WhatsApp, email, SMS, a phone number, text or a crypto request |
list_qrcodes |
List all QR codes |
update_qrcode |
Change where an existing QR code points, without reprinting it |
delete_qrcode |
Delete a QR code; printed copies stop resolving |
get_analytics |
Query click analytics |
list_domains |
List custom domains |
list_tags |
List tags |
create_tag |
Create a tag |
get_workspace |
Read the authorized workspace: name, slug and plan |
Conversion event tools are not offered. track_lead and track_sale need the
conversions.write scope, which CodeQR grants to workspace owners only, and
requesting it makes CodeQR reject the whole authorization for everyone else.
The per-link trackConversion toggle is a links.write field and IS exposed
on create_link/update_link (plans that include conversion tracking only).
Smart rules are exposed on create_link/update_link as rules: conditional
routing by any of the twelve attributes the API implements, and traffic
splitting across 2-4 destinations, which is how an A/B test is expressed — one
rule with no condition and a split. Where the workspace doesn't have smart
rules enabled, the API rejects the whole call — the create or update fails
outright, so no link or QR code is created without the rules it asked for —
and the server doesn't forward that rejection as-is: it reports that smart
rules aren't enabled on this workspace, with a link to details.
src/plan-limit-message.ts recognizes plan wording it knows: a capability
gate like this one becomes "isn't enabled on this workspace", a quota becomes
"has reached its limit of N …"; anything it doesn't recognize passes through
unchanged. Four of the field's invariants cannot be stated in JSON Schema
(weights totalling 100, url xor split, the all-or-nothing condition, the
unconditional rule coming last), so they are checked in src/smart-rules.ts
before the request is sent — which saves a round-trip and answers in a
sentence, rather than the serialized error body the SDK surfaces.
The trap worth knowing: value is compared whole and case-insensitively
against what the request carries, which for three attributes is narrower than
the name suggests. device is the operating system (iOS, Android,
Windows, Mac OS, Linux — never mobile), language a two-letter code,
referrer a bare domain. A wrong value is not an error anywhere: the API
accepts any string and the rule silently never matches.
create_qrcode/update_qrcode also take title and walletPass. title
sets the QR code's display title and is printed in large type on the
Google/Apple Wallet pass saved from the code (replacing "QR Code"). Within
walletPass, name and logo override the workspace name and logo shown on
that pass, and barcodeText sets the text shown under the QR code, e.g. a
member name or card number; when it is absent, CodeQR sends no text for that
line — the title is never repeated there. Custom branding is only available
on plans that include it, and never during a trial: a new non-null
walletPass is rejected with 403 on any other plan or during a trial, while
null (clearing it) is always accepted. Outside those plans, or during a
trial, a stored value is ignored when the pass is built, so passes fall back
to the workspace name and logo. logo is
an https URL: the API downloads it and stores its own copy, so the response
returns that copy's URL, not the one sent. barcodeText is 1-40 characters
after trimming. On update_qrcode, an object replaces the stored value as a
whole (a field left out of it is cleared, not merged) — send name, logo
and barcodeText together to keep all three; null clears the override and
reverts to the workspace branding, the same way rules: null ends a running
smart-rules test.
Interactive cards (MCP Apps)
With MCP_UI_ENABLED=1, hosts that render MCP Apps
(ChatGPT, Claude) show a card for the QR code or short link returned by
create_qrcode, update_qrcode, create_link, update_link and
get_link_info: its image, short link with a copy button, whether it is
dynamic, the destination and the scan or click count, plus a button to open it
in the CodeQR dashboard and one that asks how many scans or clicks it had.
- The tools'
_meta.ui.resourceUripoints atui://codeqr/item-card.v1.html, served throughresources/read(src/widgets/). Each read is logged asmcp.resource_read. - The result carries
structuredContent(an allowlist of fields; hosts show it to the model too) and_meta["io.codeqr/card"](image and dashboard URLs, for the card only).contentis unchanged, for clients without UI. get_analyticsgets an analytics card (ui://codeqr/analytics.v1.html): what is counted and for which period, the total, a trend line or the top five rows, and a button to open the analytics in the dashboard. Its 24h / 7d / 30d chips re-run the call from inside the card through the host (tools/call), only when the host says it can, and only with intervals every plan can read.- The pages live in
web/item-card/andweb/analytics/, with the bridge to the host inweb/shared/.yarn widgets:buildbundles them intosrc/widgets/generated/, which is committed;yarn verifyfails when it is stale. To look at them in a browser, runnode scripts/build-widgets.mjs --html, serveweb/dev/and openharness.html?fixture=qr&theme=dark&locale=pt-BR&width=375orharness.html?widget=analytics&fixture=countries&interval=30d.
Unset, the tool list, the resource list and every result are what they were.
API Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health |
No | Health check |
| GET | /.well-known/oauth-protected-resource |
No | OAuth resource metadata (RFC 9728) |
| GET | /.well-known/oauth-authorization-server |
No | OAuth server metadata (RFC 8414) |
| POST | /oauth/register |
No | Dynamic client registration (RFC 7591) |
| GET | /oauth/authorize |
No | Consent screen: which app, and where access is sent |
| POST | /oauth/authorize |
No | Consent decision; on approval redirects to CodeQR |
| GET | /oauth/callback |
No | Return leg from CodeQR |
| POST | /oauth/token |
No | Token exchange |
| POST | /mcp |
Bearer | MCP Streamable HTTP endpoint |
Architecture
src/
├── index.ts # Express app & server startup
├── config.ts # Environment configuration
├── oauth/
│ ├── store.ts # OAuth state: Upstash Redis or in-memory fallback
│ └── pkce.ts # PKCE S256 verification
├── middleware/
│ └── auth.ts # Bearer token validation middleware
└── routes/
├── well-known.ts # OAuth discovery metadata endpoints
├── oauth.ts # Authorization & token endpoints
└── mcp.ts # MCP tool definitions & handlers
Production Considerations
- OAuth persistence: Configure Upstash Redis (see
.env.example) for serverless and multi-instance deployments. Without it, the in-memory store is used (single process only). - Add rate limiting to the OAuth and MCP endpoints
- Add HTTPS (usually handled by your reverse proxy / platform)
- Add monitoring (the
/healthendpoint is ready for probes) - Consider token rotation for long-lived sessions
Publishing to the MCP Registry
This server is listed in the official registry as io.codeqr/codeqr. The registry
stores only the metadata in server.json — never the code.
Publishing is authorized by DNS: a TXT record on the apex of codeqr.io holds
the public half of an Ed25519 key pair. Apex, not a selector — MCP DNS auth follows
SPF-style placement, and a record under _mcp-auth. fails with a generic signature
error that does not name the cause.
# 1. Bump the version in package.json, src/config.ts and server.json together.
# `yarn test` fails if they drift — the registry refuses to republish a
# version it already has.
#
# Then bump it in the CodeQR app too: the Server Card at
# app/.well-known/mcp/server-card.json/route.ts advertises this server's
# version, and no test can reach across repos to check. It already drifted
# once, to a release that never existed.
# 2. Authenticate with the private key (kept outside this repo).
PRIVATE_KEY="$(openssl pkey -in /path/to/codeqr-io.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')"
mcp-publisher login dns --domain codeqr.io --private-key "$PRIVATE_KEY"
# 3. Publish, then confirm the entry is live.
mcp-publisher publish
curl "https://registry.modelcontextprotocol.io/v0/servers?search=codeqr"
If the key is ever rotated, remove the old TXT record — a stale one is tried first and makes verification fail.
Directory listings
Aggregators crawl the ecosystem and list servers whether or not anyone claims them, so an unclaimed entry still exists — as a bot's guess at what this server does. Claiming replaces the guess and unlocks editing the name and description a reader sees. None of this is done by merging a file; each one is a one-time action on the aggregator's own site.
| Directory | How ownership is claimed | Status |
|---|---|---|
| Official MCP Registry | mcp-publisher + DNS, as above |
listed |
| Glama | glama.json in this repo, then run the claim flow once from an account listed in maintainers |
file in repo; claim pending |
| Smithery | smithery mcp publish https://mcp.codeqr.io/mcp -n <org>/<name> |
pending |
| PulseMCP | hand-reviewed submission on their site | pending |
| mcp.so | submission form / GitHub issue | pending |
The GitHub OAuth route Glama also offers only associates repos under a personal
account, which this repo is not — it belongs to the codeqr-io org. Hence the file.
License
MIT — CodeQR
CodeQR MCP 질문
CodeQR MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --transport http codeqr-mcp-remote https://mcp.codeqr.io/mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
CodeQR MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
CodeQR MCP는 어떤 도구를 제공하나요?
14개 도구를 제공합니다. 예: create_link, list_links, get_link_info, update_link, delete_link.
이 MCP server는 API key가 필요한가요?
아니요, OAuth 2.0 인증을 사용합니다. 동의 화면을 통해 액세스를 승인하므로 API key를 직접 다룰 필요가 없습니다.
기존 QR 코드를 다시 인쇄하지 않고 업데이트할 수 있나요?
네, 업데이트 도구를 사용하여 기존 QR 코드가 연결되는 목적지를 변경할 수 있습니다.
저장소로 Upstash Redis를 사용하지 않으면 어떻게 되나요?
서버는 인메모리 저장소를 사용하며, 이는 로컬 개발 환경에만 적합합니다.