Jira Assets MCP Server

A minimal Model Context Protocol server that gives an AI client read and write access to Atlassian Jira Assets (formerly Insight), plus a review dashboard for bulk editing.

The official Atlassian MCP connector covers Jira issues and Confluence pages. It does not cover Assets. If your CMDB, license register, hardware inventory, or vendor catalogue lives in Assets, this closes the gap.

Companion article on MEDIUM: Your CMDB Is Invisible to Your AI Assistant. Here Is How I Fixed That in One Evening. https://medium.com/@Road2DevNull/your-cmdb-is-invisible-to-your-ai-assistant-here-is-how-i-fixed-that-in-one-evening-5630ca6dbebc

---

What you get

File	Purpose
assets_mcp_server.mjs	The MCP server. Five tools, two dependencies.
dashboard.html	Self-contained review dashboard. Bulk edit, one-click push.
store-credential.ps1	One-time setup: stores the API token in Windows Credential Manager.
read-credential.ps1	Runtime helper: the server calls this to read the token back.
claude_desktop_config.example.json	Config template. No token in it, only a credential target name.
package.json	Dependency manifest.

Tools exposed

Tool	Direction	Description
get_assets	read	Fetch all objects with flattened field values
discover_schema	read	List attribute names and numeric IDs. Run this first.
update_auto_renewal	write	Set the auto renewal flag on one object
update_payment_method	write	Set the payment method on one object
apply_bulk_changes	write	Apply changes to many objects in one call

---

Quick start

1. Install

git clone <this-repo>
cd assets-mcp
npm install

2. Find your workspace ID

The Assets API does not live on your Jira hostname. It sits behind a workspace-scoped gateway.

curl -u you@example.com:YOUR_API_TOKEN \
  https://your-site.atlassian.net/rest/servicedeskapi/assets/workspace

Copy the workspaceId UUID from the response.

3. Find your schema and object type IDs

Open the object type in the Assets UI and read them straight from the URL:

/jira/assets/object-schema/{schemaId}?typeId={objectTypeId}

4. Create an API token

Go to id.atlassian.com/manage-profile/security/api-tokens, create a token, and copy it immediately. It is shown once. Prefer a scoped token, restricted to the narrowest scopes the integration needs, over a classic full-account one.

5. Store the token in your OS credential store, not in a config file

Do this before touching any config file. On Windows:

powershell -NoProfile -ExecutionPolicy Bypass -File store-credential.ps1 -Target "AssetsMCP"

This prompts for the token with a masked input, so it is never typed as a command-line argument and never lands in shell history, and stores it via the native Windows CredWrite API, encrypted and tied to your Windows profile.

Verify it landed correctly before configuring the server:

powershell -NoProfile -ExecutionPolicy Bypass -File read-credential.ps1 -Target "AssetsMCP"

It should print the token back. If you're on macOS or Linux, swap this pair of scripts for your platform's equivalent (Keychain via the security CLI, or the Secret Service API via secret-tool); same pattern, different retrieval call.

6. Configure your MCP host

Copy claude_desktop_config.example.json into your host's config and fill in the values. Notice there is no token field to fill in, only email, workspace details, and the credential target name you used in step 5.

Config file locations:

OS	Path
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Use forward slashes in the args path, even on Windows.

7. Restart your MCP host

Quit fully, including any system tray icon, then relaunch. The server is spawned on startup, reads the credential target from its environment, and pulls the token from the credential store at that point.

8. Discover your attribute IDs

Ask your client to run discover_schema. Output looks like:

    ID  NAME
  1001  Name
  1004  Status
  1009  Auto renewal
  1010  Payment method

Paste those IDs into the ATTR map at the top of assets_mcp_server.mjs. Copy the names exactly, casing included. They are case sensitive and frequently inconsistent.

9. Verify

Ask your client:

Call get_assets and tell me how many objects came back, and how many unique keys are in the result.

If total and unique differ, pagination is duplicating records. See Pitfall 3 below.

10. Open the dashboard (optional)

Update the two tool name constants at the top of the <script> block in dashboard.html:

const MCP_READ  = 'mcp__assets__get_assets';
const MCP_WRITE = 'mcp__assets__apply_bulk_changes';

The assets segment must match the server key you used in your host config.

---

Known API pitfalls

These four cost me hours. They are documented here so they do not cost you the same.

1. Wrong base URL

Assets is not at your-site.atlassian.net. It is at:

https://api.atlassian.com/jsm/assets/workspace/{workspaceId}/v1

The workspaceId is a UUID and is not your cloud ID.

2. AQL returns attribute IDs, not names

An AQL response gives you objectTypeAttributeId (a bare number). A single-object GET gives you objectTypeAttribute.id plus a name. Handle both shapes or half your reads silently return empty strings.

const id = String(a.objectTypeAttributeId ?? a.objectTypeAttribute?.id ?? "");

3. startAt in the POST body is ignored

POST /object/aql honours maxResults in the body but silently ignores startAt. You get HTTP 200 and page one, forever.

// Wrong
body: JSON.stringify({ qlQuery, maxResults, startAt })

// Right
const url = `${BASE_URL}/object/aql?startAt=${startAt}`;

Also: adding includeAttributesDeep to the body breaks pagination entirely, even with the query parameter fix. Do not use it.

Always include ORDER BY in your AQL so page boundaries stay stable across requests.

4. Attribute names are case sensitive

Real schemas are inconsistently cased. Auto renewal and Payment method both use a lowercase second word. Copy names from discover_schema output. Never type them from memory.

---

Security

Read this before deploying.

Property	Reality
Authentication	Basic Auth, personal API token
Token storage	OS credential store (Windows Credential Manager / DPAPI). No plaintext copy on disk.
Transport	stdio, local process, no listening port
Identity	Individual user, not a service account
Scope	Read and write on one Assets object type
Network exposure	None
Third parties	None. Atlassian only.
Audit trail	Native. All writes appear in Jira object history.

Why Basic Auth and not OAuth

The Assets workspace gateway rejects OAuth bearer tokens even when the token carries valid Assets scopes. Basic Auth with an API token is the only reliable path today. This is a real tradeoff, not a preference.

Why the credential store, and not a config file

A plaintext secret in an application config file is one of the most common findings in any review of internal tooling, common enough to have its own classification, CWE-798, Use of Hard-Coded Credentials. It is also cheap to avoid entirely. This server reads its token from the OS credential store at startup and never writes it to disk in plaintext, so a copied config file, a synced backup, or a support-ticket paste of the wrong file hands over nothing usable.

What this does not solve, read this part too

The credential store protects data at rest. It does not change what happens if code is already running under your own logged-in session: an attacker with an active foothold can call the same CredRead API this server calls and get the plaintext back just as easily. The blast radius of an active compromise is unchanged; what shrinks is the blast radius of a passive one (theft of a file, an accidental copy, a backup sync).

Other limits worth knowing:

• It is still a personal credential, not a service account. Storage hardening doesn't answer who owns it after an offboarding, that still needs a rotation and revocation process.
• It is platform-specific. Windows Credential Manager has no meaning on macOS or Linux; porting means swapping the retrieval call for Keychain or Secret Service.
• It adds one more moving part at startup: a helper process that can fail (execution policy, a missing script, a locked profile).
• It is not a substitute for an enterprise secrets manager. No centralized rotation policy, no expiry enforcement, no access-controlled audit log of who read the secret and when. Good step up from a config file; not equivalent to Vault or a cloud KMS-backed secret if this ever needs to run for more than one person.

Recommended mitigations on top of this, in order of impact:

1. Rotate the token on a schedule; add it to your offboarding checklist
2. Prefer a scoped token over a classic full-account one, restricted to minimum viable permissions
3. Provision a dedicated account rather than a personal identity, once this scales beyond one user
4. If this needs to run on a shared or server host rather than a personal workstation, move to a proper secrets manager instead of an OS credential store

What is genuinely better than the alternative

Every write goes through the Assets REST API, so every change lands in the object's native change history, attributed and timestamped. The CSV export and re-import workflow this replaces has no comparable audit trail.

---

Adapting to a different object type

The server is not license specific. To point it at hardware, contracts, vendors, or anything else:

1. Change ASSETS_OBJECT_TYPE_ID in your config
2. Run discover_schema and replace the ATTR map
3. Rename the fields in summariseObject() to match your domain
4. Adjust WRITABLE_ATTRS and the write tool schemas for the fields you want editable

The pagination, auth, and attribute extraction logic is generic and needs no changes.

---

Requirements

• Node.js 18 or later (native fetch)
• @modelcontextprotocol/sdk
• zod

---

License

MIT. All identifiers in this repository are placeholders.