Atlas Goals

CLI and MCP server for managing Atlassian Goals (Atlas / Townsquare) via the GraphQL API.

Search, create, edit, audit, and reorganise OKRs from your terminal — or wire it into Claude Desktop / Claude Code as an MCP server for AI-assisted goal management.

Features

• Search & read goals, types, tags, and teams
• Create, edit, archive goals with full field support
• Hierarchy — tree view, reparent, bulk reparent
• Tags & teams — add/remove tags, link/unlink teams
• Metrics / KPIs — add and edit metric targets
• Users — whoami, user search, --owner me auto-resolution
• Audit — flag goals missing owner, dates, tags, KPIs, parent, etc.
• MCP server — every command exposed as an MCP tool

Quick start

git clone https://github.com/mtnnn/atlas.git
cd atlas
pnpm install
pnpm build
npm link              # makes `atlas` and `atlas-mcp` available globally

cp .env.example .env  # then fill in your values (see below)

atlas whoami          # verifies your credentials
atlas search          # lists goals in your workspace

Requires: Node ≥ 18 and pnpm.

Configuration

Create a .env file in the project root with the following:

Variable	Description
ATLASSIAN_SITE	Your Atlassian Cloud subdomain (the part before .atlassian.net)
ATLASSIAN_EMAIL	Email for your Atlassian account
ATLASSIAN_API_TOKEN	API token — see below
ATLASSIAN_CONTAINER_ID	Workspace ARI for goal searches — see below

Getting an API token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token → give it a label like "atlas-cli" → copy the token
3. Paste it as ATLASSIAN_API_TOKEN in your .env

Finding your ATLASSIAN_CONTAINER_ID

The container ID is a workspace ARI like ari:cloud:townsquare:abc123:workspace/def456.

1. Open Atlas in a browser (https://<site>.atlassian.net/o/...)
2. Open DevTools → Network tab
3. Search/scroll to any goal — filter requests for goals_search or GoalSearch
4. Open the request payload, copy the containerId value

Usage

atlas <command> [options]

Run atlas help for the full command list. Highlights:

Command	Description
search [query]	Search goals — substring match against the goal name, case-insensitive (--sort, --first, --include-archived)
get <goalId>	Get full goal details by ARI or key (e.g. WORKSPACE-123)
types	List available goal types
audit	Audit goals for completeness (--search, --tag)
tree	Display goal hierarchy (--root, --tag)
create <name>	Create a goal (--type, --owner, --desc, --target-date, --start-date, --parent)
edit <goalId>	Edit a goal (--name, --desc, --owner, --target-date, --start-date)
archive <goalId>	Archive a goal
set-parent <goalId> <parentId>	Reparent a goal (use null for top-level)
bulk-set-parents --json '[...]'	Batch reparent goals
by-tag <tagName> / tags	Filter / list tags
by-team <teamName> / teams	Filter / list teams
add-tag / remove-tag	Manage tags on a goal
link-team / unlink-team	Manage teams on a goal
add-metric / edit-metric	Manage KPIs
whoami / users <query>	User lookup

Owner resolution

The --owner flag on create and edit accepts:

• A raw Atlassian account ID
• me — auto-resolves to the authenticated user

MCP server (Claude Desktop / Claude Code)

Every CLI command is also exposed as an MCP tool via atlas-mcp. Add to your MCP client config:

{
  "mcpServers": {
    "atlas-goals": {
      "command": "atlas-mcp"
    }
  }
}

The MCP server reads the same .env from the project root.

Architecture

src/
  index.ts          CLI entrypoint
  mcp.ts            MCP server entrypoint
  config.ts         Environment config loader
  rate-limiter.ts   Token-bucket rate limiter (10k pts/min Atlassian limit)
  types.ts          TypeScript interfaces
  graphql/
    client.ts       GraphQL client with pagination
    fragments.ts    Reusable GraphQL fragments
    queries.ts      Search and read queries
    mutations.ts    Create, edit, link mutations
  tools/
    search.ts       Search, get, types, key→ARI resolution
    audit.ts        Goal completeness audit
    hierarchy.ts    Tree view and reparenting
    lifecycle.ts    Create, edit, archive
    tags.ts         Tag and team listing/filtering
    metrics.ts      KPI management
    teams.ts        Team linking
    users.ts        User lookup and owner resolution

Development

pnpm install
pnpm build         # compile TS → build/
pnpm test          # run unit tests (Vitest)
pnpm test:watch    # watch mode
pnpm dev           # tsc --watch

See TESTING.md for the manual smoke-test checklist used before releases.

API notes

• Goal IDs are ARIs: ari:cloud:townsquare:{siteId}:goal/{uuid}
• kind: GOAL = Objective, kind: SUCCESS_MEASURE = Key Result
• Tags are called "focusAreas" in the Atlassian API
• The Atlas / Townsquare GraphQL endpoint is undocumented; this client is built from observed traffic. Atlassian may change the schema without notice.
• Rate limit: 10,000 points / minute (handled automatically by rate-limiter.ts)

Contributing

Issues and PRs welcome. For larger changes, please open an issue first to discuss the approach. Run pnpm build && pnpm test before submitting; check the manual smoke checklist in TESTING.md if your change touches the CLI surface.

License

MIT © Martijn van Rookhuijzen