@atoms-tech/atoms-mcp

MCP server for ATOMS.tech — connect AI agents to your requirements management workspace.

Quick Start

# 1. Login to your ATOMS account
npx @atoms-tech/atoms-mcp login

# 2. Add to Claude Code
claude mcp add atoms-mcp -- npx @atoms-tech/atoms-mcp

That's it. Claude can now read, create, and manage requirements in your ATOMS projects.

What It Does

ATOMS MCP gives AI agents direct access to your requirements, test cases, and traceability data through the Model Context Protocol. Agents can:

• Browse and filter items with an interactive viewer
• Create and update requirements with an inline editor
• Search requirements, test cases, and notes
• Bulk import up to 100 items at a time
• Link items with parent/child and verification relationships
• Record test results and check coverage gaps
• Trace requirement/test relationships upstream and downstream
• Generate traceability diagrams as Mermaid graphs
• View project compliance dashboards

Every action is logged with AI actor attribution (mcp_claude) and enforces your organization's role-based permissions.

Available Tools

| Tool | Description | Access | MCP App UI | |------|-------------|--------|------------| | atoms_status | Health check and auth status | Read | | | atoms_list_projects | List all accessible projects | Read | | | atoms_list_items | Browse items with type/domain/level filters | Read | | | atoms_get_item | Get full item details with relationships | Read | | | atoms_search | Full-text search across items | Read | | | atoms_browse | Interactive filterable item viewer | Read | Browse viewer | | atoms_get_coverage | Find requirements without test cases | Read | Coverage heatmap | | atoms_get_history | Audit trail for an item | Read | | | atoms_export_mermaid | Generate traceability diagram | Read | | | atoms_trace | Walk traceability graph (upstream/downstream) | Read | Force-directed graph | | atoms_project_summary | Project compliance dashboard | Read | Charts + gauges | | atoms_impact_analysis | Analyze change impact across items | Read | | | atoms_list_variables | List parameterized variables | Read | | | atoms_get_variable | Get variable with references | Read | | | atoms_update_variable | Update variable value | Write | | | atoms_create_item | Create a requirement, test case, or note | Write | Inline editor | | atoms_update_item | Update item fields | Write | Inline editor | | atoms_delete_item | Soft-delete an item | Write | | | atoms_link_items | Add/remove relationships between items | Write | | | atoms_bulk_import | Bulk create up to 100 items at once | Write | Results table | | atoms_record_test_result | Record pass/fail for a test case | Write | |

Interactive UIs (MCP Apps)

7 tools include interactive UIs powered by MCP Apps. In supported hosts (Claude.ai, ChatGPT), these tools render rich visualizations inline in the conversation:

• Browse Viewer — filterable item list with type, domain, level, and search controls. Click items to expand detail inline.
• Inline Editor — editable card for created/updated items. Refine title, summary, body, domains, and level directly in chat. Saves on blur.
• Project Summary — compliance dashboard with coverage gauge, test status bar, and domain charts
• Trace Graph — interactive force-directed graph with depth stepper and direction controls
• Coverage Heatmap — visual coverage report with uncovered requirements list
• Bulk Import Results — color-coded table showing created items and errors

In non-UI clients (Claude Code CLI, Cursor, Claude Desktop), these tools return standard JSON text — no functionality is lost.

Authentication

ATOMS MCP uses OAuth 2.1 with PKCE — the same flow used by GitHub CLI and Supabase CLI.

# Interactive login (opens browser)
npx @atoms-tech/atoms-mcp login

# Check current session
npx @atoms-tech/atoms-mcp whoami

# Clear credentials
npx @atoms-tech/atoms-mcp logout

How it works:

1. login opens your browser to the ATOMS consent page
2. You approve the MCP connection with your ATOMS account
3. Tokens are stored locally at ~/.atoms/credentials.json
4. Tokens auto-refresh — you only need to login once

You can also set ATOMS_ACCESS_TOKEN as an environment variable for CI/headless use.

CLI Commands

npx @atoms-tech/atoms-mcp login     # Authenticate with ATOMS
npx @atoms-tech/atoms-mcp logout    # Clear stored credentials
npx @atoms-tech/atoms-mcp whoami    # Show current user
npx @atoms-tech/atoms-mcp --help    # Show all commands

Running without a subcommand starts the MCP server on stdio.

Setup

Claude Code

claude mcp add atoms-mcp -- npx @atoms-tech/atoms-mcp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "atoms-mcp": {
      "command": "npx",
      "args": ["@atoms-tech/atoms-mcp"]
    }
  }
}

Cursor / Windsurf

Add to your MCP configuration with command: "npx" and args: ["@atoms-tech/atoms-mcp"]. Refer to your editor's MCP documentation for the exact config file location.

Security

• Row Level Security (RLS) — All queries run with the user's JWT. The server never uses a service role key. You can only access projects your organization has granted you access to.
• Role enforcement — Write tools check your org role (viewer, editor, admin) before making changes. Viewers are blocked from mutations.
• Audit logging — Every tool call is logged with tool name, parameters, duration, and session ID. Write operations log to change_history with actor: "mcp_claude".
• Rate limiting — Built-in per-user rate limiter prevents abuse.
• No secrets in the package — The Supabase anon key is a publishable client key (like a Firebase API key). It grants zero data access without a valid user JWT.

Requirements

• Node.js >= 18
• An ATOMS.tech account with at least one project

Links

• ATOMS.tech — Requirements management platform
• Model Context Protocol — Open standard for AI tool integration
• GitHub — Source code

License

Proprietary. See LICENSE for details.