@radsoft/markbase-mcp 2026.8.1

package/README.md

@@ -0,0 +1,75 @@
+# Markbase MCP
+
+An [MCP](https://modelcontextprotocol.io) server for the [Markbase](https://markbase.co)
+USPTO trademark API. Gives an assistant the ability to search US trademarks, screen a
+proposed brand name for conflicts, and pull registration records — grounded in the
+actual federal register instead of guessed from training data.
+
+Covers the **USPTO only** (14M+ US marks). If you need EUIPO, WIPO, or UKIPO, a
+multi-office platform is a better fit.
+
+## Setup
+
+You need a free API key — [get one at markbase.co](https://markbase.co/login).
+5,000 requests a month, no card.
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "markbase": {
+      "command": "npx",
+      "args": ["-y", "@radsoft/markbase-mcp"],
+      "env": {
+        "MARKBASE_API_KEY": "mb_your_key_here"
+      }
+    }
+  }
+}
+```
+
+For Claude Code:
+
+```bash
+claude mcp add markbase --env MARKBASE_API_KEY=mb_your_key -- npx -y @radsoft/markbase-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `check_trademark_availability` | Screen a proposed name against the register, ranked by similarity with a risk level |
+| `search_trademarks` | Typo-tolerant search across 14M+ marks, filterable by class and status |
+| `get_trademark` | Full record for one mark by serial number |
+| `get_trademark_timeline` | Prosecution history — filing, publication, office actions, registration |
+| `search_by_owner` | Every mark held by a company or person |
+| `list_trademark_classes` | All 45 Nice classes, so the model can pick the right one before screening |
+
+## Why the class matters
+
+Trademark rights are scoped to goods and services. DELTA coexists as an airline, a
+faucet maker, and dental insurance. Screening a name without a class produces noise —
+pass `trademark_class` and you get only marks that could actually block you.
+
+```
+check_trademark_availability({ name: "Acme", trademark_class: "9" })
+```
+
+## Not legal advice
+
+These tools return a first-pass screening signal over the federal register. They do
+not cover state trademarks, common-law rights, or the legal analysis of likelihood
+of confusion. Treat a clean result as "worth pursuing", not "cleared", and recommend
+a trademark attorney for any name a user intends to actually adopt.
+
+## Environment
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `MARKBASE_API_KEY` | yes | — |
+| `MARKBASE_API_URL` | no | `https://api.markbase.co` |
+
+## License
+
+MIT — a product of [Rad Soft](https://radsoftinc.com).

package/dist/client.js

@@ -0,0 +1,104 @@
+const BASE = process.env.MARKBASE_API_URL || "https://api.markbase.co";
+const KEY = process.env.MARKBASE_API_KEY;
+// the api is public, so this isn't a lock — it's so every mcp user is a real
+// account we can see and support, instead of anonymous traffic on a shared ip quota
+export function requireKey() {
+    if (!KEY) {
+        throw new Error("MARKBASE_API_KEY is not set. Get a free key at https://markbase.co/login " +
+            "(5,000 requests/month, no card), then add it to your MCP client config as " +
+            'an env var: { "env": { "MARKBASE_API_KEY": "mb_..." } }');
+    }
+    return KEY;
+}
+// lets us measure how much traffic the mcp actually drives, separately from
+// direct api use, in api_requests
+const UA = "markbase-mcp/0.1.0";
+export class MarkbaseError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export async function request(path, init) {
+    const key = requireKey();
+    const res = await fetch(`${BASE}${path}`, {
+        ...init,
+        headers: {
+            accept: "application/json",
+            "user-agent": UA,
+            ...(init?.body ? { "content-type": "application/json" } : {}),
+            "x-api-key": key,
+            ...init?.headers,
+        },
+    });
+    const text = await res.text();
+    let body;
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        body = { error: text.slice(0, 200) };
+    }
+    if (!res.ok) {
+        // surface quota state, since the most common failure on the keyless tier is
+        // running out of month rather than anything the caller did wrong
+        const remaining = res.headers.get("x-quota-remaining");
+        const detail = res.status === 401
+            ? "Invalid MARKBASE_API_KEY. Get a key at https://markbase.co/login"
+            : res.status === 429 && remaining === "0"
+                ? `${body.error || "monthly quota exceeded"}. Your plan resets monthly — see https://markbase.co/#pricing to raise it.`
+                : body.error || `request failed (${res.status})`;
+        throw new MarkbaseError(detail, res.status);
+    }
+    return body;
+}
+export function padClass(v) {
+    return /^\d+$/.test(v) ? v.padStart(3, "0") : v;
+}
+// numeric USPTO status codes are meaningless to a model without this
+export function statusLabel(code) {
+    if (!code)
+        return "unknown";
+    const n = parseInt(code, 10);
+    if (Number.isNaN(n))
+        return "unknown";
+    if (n >= 600 && n < 700)
+        return "dead";
+    if (n >= 710 && n < 720)
+        return "cancelled";
+    if (n >= 900)
+        return "expired";
+    if (n >= 800 || n === 700 || (n >= 730 && n < 740))
+        return "registered";
+    if (n < 600)
+        return "pending";
+    return "registered";
+}
+export function isoDate(d) {
+    if (!d || d.length !== 8)
+        return null;
+    return `${d.slice(0, 4)}-${d.slice(4, 6)}-${d.slice(6, 8)}`;
+}
+// models do better with labelled fields than with raw uspto codes
+export function shapeMark(m) {
+    // the register uses all-zero placeholders for "none"; a model will happily
+    // report "registration number 0000000" if we pass that through
+    const reg = m.registration_number && /[1-9]/.test(m.registration_number)
+        ? m.registration_number
+        : null;
+    return {
+        serial_number: m.serial_number,
+        registration_number: reg,
+        mark: m.word_mark,
+        owner: m.owner_name,
+        owner_country: m.owner_country,
+        status: statusLabel(m.status_code),
+        status_code: m.status_code,
+        filed: isoDate(m.filing_date),
+        registered: isoDate(m.registration_date),
+        // a mark can list the same class twice across its filing basis rows
+        classes: [...new Set(m.international_codes?.map((c) => String(parseInt(c, 10))) ?? [])],
+        goods_services: m.goods_services,
+    };
+}

package/dist/index.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { request, padClass, shapeMark, MarkbaseError } from "./client.js";
+const server = new McpServer({
+    name: "markbase",
+    version: "0.1.0",
+});
+// every tool returns text content; errors come back as isError so the model can
+// recover rather than seeing a transport failure
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function fail(err) {
+    const msg = err instanceof MarkbaseError ? err.message : err.message;
+    return {
+        content: [{ type: "text", text: `Markbase error: ${msg}` }],
+        isError: true,
+    };
+}
+server.registerTool("search_trademarks", {
+    title: "Search US trademarks",
+    description: "Full-text, typo-tolerant search across 14M+ USPTO trademark records. Use this to find existing marks by name. Filter by class to scope to relevant goods/services, and by status to exclude dead marks.",
+    inputSchema: {
+        query: z.string().describe("Mark name or text to search for, e.g. 'nike'"),
+        trademark_class: z
+            .string()
+            .optional()
+            .describe("Nice class 1-45 to scope results, e.g. '9' for software"),
+        live_only: z
+            .boolean()
+            .optional()
+            .describe("Only return registered/live marks (status 800). Defaults to false."),
+        limit: z.number().int().min(1).max(25).optional().describe("Max results, default 10"),
+    },
+}, async ({ query, trademark_class, live_only, limit }) => {
+    try {
+        const p = new URLSearchParams({ q: query, limit: String(limit ?? 10) });
+        if (trademark_class)
+            p.set("international_code", padClass(trademark_class));
+        if (live_only)
+            p.set("status_code", "800");
+        const data = await request(`/search?${p}`);
+        return ok({
+            total_matches: data.total_hits,
+            note: data.total_hits >= 1000
+                ? "total_matches is capped at 1000; narrow with a class filter for a precise count"
+                : undefined,
+            results: data.hits.map(shapeMark),
+        });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("check_trademark_availability", {
+    title: "Screen a proposed name against existing trademarks",
+    description: "Screen a proposed brand or company name against the US register and get existing marks ranked by similarity, each with a risk level. Use this BEFORE suggesting a company, product, or brand name to a user. This is a first-pass screening signal, not legal advice.",
+    inputSchema: {
+        name: z.string().describe("The proposed brand or company name to screen"),
+        trademark_class: z
+            .string()
+            .optional()
+            .describe("Nice class 1-45 for the goods/services. Strongly recommended — trademark rights are class-scoped, so screening without one produces noise."),
+        limit: z.number().int().min(1).max(25).optional().describe("Max conflicts to return, default 10"),
+    },
+}, async ({ name, trademark_class, limit }) => {
+    try {
+        const p = new URLSearchParams({ mark: name, limit: String(limit ?? 10) });
+        if (trademark_class)
+            p.set("class", padClass(trademark_class));
+        const data = await request(`/clearance?${p}`);
+        return ok({
+            proposed_name: data.mark,
+            scoped_to_class: data.class ? String(parseInt(data.class, 10)) : null,
+            highest_risk: data.highest_risk,
+            conflicts: data.matches.map((m) => ({
+                ...shapeMark(m),
+                similarity: m.similarity,
+                risk: m.risk,
+            })),
+            disclaimer: "Screening signal only. Likelihood of confusion is a legal judgment and this does not cover state or common-law rights. Recommend a trademark attorney before adopting a name.",
+        });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("get_trademark", {
+    title: "Get a trademark by serial number",
+    description: "Fetch the complete record for one US trademark by its USPTO serial number, including owner, status, classes, and goods/services.",
+    inputSchema: {
+        serial_number: z.string().describe("USPTO serial number, e.g. '72414177'"),
+    },
+}, async ({ serial_number }) => {
+    try {
+        const data = await request(`/trademark/${encodeURIComponent(serial_number)}`);
+        return ok(shapeMark(data));
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("get_trademark_timeline", {
+    title: "Get a trademark's prosecution history",
+    description: "Fetch the event timeline for a US trademark — filing, publication, office actions, registration, and any abandonment or cancellation.",
+    inputSchema: {
+        serial_number: z.string().describe("USPTO serial number, e.g. '72414177'"),
+    },
+}, async ({ serial_number }) => {
+    try {
+        const data = await request(`/trademark/${encodeURIComponent(serial_number)}/timeline`);
+        return ok(data);
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("search_by_owner", {
+    title: "List trademarks held by an owner",
+    description: "Find every US trademark held by a person or company. Use this to inspect a competitor's or a client's trademark portfolio.",
+    inputSchema: {
+        owner: z.string().describe("Owner name, e.g. 'Nike, Inc.'"),
+        limit: z.number().int().min(1).max(25).optional().describe("Max results, default 10"),
+    },
+}, async ({ owner, limit }) => {
+    try {
+        const p = new URLSearchParams({ name: owner, limit: String(limit ?? 10) });
+        const data = await request(`/owner?${p}`);
+        return ok({ total_matches: data.total_hits, results: data.hits.map(shapeMark) });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("list_trademark_classes", {
+    title: "List the 45 trademark classes",
+    description: "List all 45 Nice Classification classes with their titles. Use this to pick the right class before screening a name — classes 1-34 are goods, 35-45 are services.",
+    inputSchema: {},
+}, async () => {
+    try {
+        const data = await request("/classes");
+        return ok(data.classes.map((c) => ({
+            class: String(parseInt(c.code, 10)),
+            title: c.title,
+            kind: parseInt(c.code, 10) >= 35 ? "services" : "goods",
+        })));
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@radsoft/markbase-mcp",
+  "version": "2026.8.1",
+  "description": "MCP server for the Markbase USPTO trademark API \u2014 search, screen, and look up US trademarks from any MCP client.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "markbase-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "trademark",
+    "uspto",
+    "trademark-search",
+    "clearance",
+    "markbase"
+  ],
+  "homepage": "https://markbase.co",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rad-Soft/marked-api.git",
+    "directory": "mcp"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}