Geeks AMP MCP Server

Local MCP server for Cursor and Claude that authenticates to your AMP backend via OAuth 2.0 (Authorization Code + PKCE) and proxies tool calls to AMP’s MCPServer.ashx.

Using this as a developer? See DEVELOPER.md for Cursor and Claude setup, example prompts, and how AMP MCP can help in day-to-day work.

Flow

1. First use – When you call an AMP tool, the server opens your browser to AMP’s login. After you sign in, AMP redirects to http://127.0.0.1:5005/callback. The server exchanges the code for access and refresh tokens and stores them (e.g. in ~/.amp-mcp/credentials.json).
2. Later uses – The server reuses the stored access token. When it expires, it uses the refresh token; if refresh fails, it runs the browser flow again.
3. Tools – get_user_projects, get_projects, get_amp_item, get_workplans, get_active_workplans, get_workplan_items, get_amp_comments, get_amp_item_with_test_cases, create_amp, add_amp_update, submit_amp_progress_update, add_amp_test_case_references, submit_pen_test_review, audit_tdd_amp, and audit_pen_test_amp are forwarded to AMP with Authorization: Bearer <token>. get_auth_status reports the local authentication state without calling AMP.

Prerequisites

• Node.js 18+
• AMP running with OAuth client amp-cursor-mcp and redirect URI http://127.0.0.1:5005/callback (see Website/web.config).

Setup

cd geeks-amp-mcp
npm install
npm run build

Cursor config

In .cursor/mcp.json (project or global), use the local server via npx (no env token). From the repo root (geeksamp), run the package with:

{
  "mcpServers": {
    "amp": {
      "command": "npx",
      "args": ["./geeks-amp-mcp"],
      "env": {
        "AMP_BASE_URL": "http://localhost:39290",
        "AMP_OAUTH_CLIENT_ID": "amp-cursor-mcp",
        "AMP_CALLBACK_PORT": "5005"
      }
    }
  }
}

• npx ./geeks-amp-mcp – Runs the local package’s bin (uses geeks-amp-mcp/dist/index.js). Cursor’s working directory is the workspace root, so the path is relative to that. Restart Cursor after changing MCP config.
• To use an absolute path instead: "args": ["C:\\path\\to\\geeksamp\\geeks-amp-mcp"] with "command": "npx", or "command": "node" and "args": ["C:\\path\\to\\geeksamp\\geeks-amp-mcp\\dist\\index.js"].
• Plain npx geeks-amp-mcp (no path) only works if the package is installed from npm. If you publish geeks-amp-mcp to the registry, users can run npx geeks-amp-mcp from any directory and set AMP_BASE_URL etc. in env.

Publishing to npm

1. Create an account at npmjs.com.
2. In geeks-amp-mcp, run npm run build, then npm login and npm publish.
3. If the name geeks-amp-mcp is taken, use a scoped name in package.json (e.g. "name": "@your-org/geeks-amp-mcp"); then publish with npm publish --access public so others can install it without a paid plan.
4. Update package.json repository.url (replace YOUR_ORG with your GitHub org/user) before publishing.

Env (optional)

| Variable | Default | Description | |----------|---------|-------------| | AMP_BASE_URL | http://localhost:39290 | AMP base URL | | AMP_OAUTH_CLIENT_ID | amp-cursor-mcp | OAuth client id (must match AMP) | | AMP_CALLBACK_PORT | 5005 | Callback listener port (must be in AMP redirect URIs) | | AMP_MCP_CREDENTIALS_DIR | ~/.amp-mcp | Directory for stored tokens |

Tools

• get_auth_status – Returns Authenticated: YES or Authenticated: NO (no browser).
• get_user_projects – Non-archived projects the authenticated user belongs to: { projects: [{ id, key, name }] }, ordered by key. Use this before create_amp.
• get_projects – Legacy global project search (optional searchTerm, limit); returns id + name only, not user-scoped. Do not use for create flows.
• get_amp_item – Rich details for an authorized AMP by ampReference (12345 or AMP-12345): metadata, project, type, priority, status/progress/stage, completion, assignees, workplans, tags, URLs, linked AMPs, extension relationships (extendedFrom, extensions), pen-test review fields, and test case references. It does not return full comment history; use get_amp_comments for the conversation.
• get_workplans – All workplans in a project (active and inactive), including Backlog. Required: project (key or GUID). Returns name, dates, teams, and isActive. Use get_workplan_items with a workplan name or GUID to load that plan's AMPs.
• get_active_workplans – Active workplans for a project (there may be several). Required: project (key or GUID). Returns dates, teams, estimate/duration, completion %, and item counts. Use get_workplan_items with a workplan name or GUID to load that plan's AMPs.
• get_workplan_items – All items in a workplan, assigned to any user. Required: project. Optional: workplan (name or GUID from get_workplans / get_active_workplans; omit for the newest active plan), assignee (name, email, or user GUID), progress (Not started, TDD, Developing, Testing, Done, Blocked). Returns workplan metadata, applied filters, and items in workplan order.
• get_amp_comments – Authorized AMP comment history, newest first. Required: ampReference. Optional: column (Team, Client, Director, or all) and limit (1–500). With no column, AMP returns every column visible to the authenticated user's role; with no limit, it returns all visible comments. The response reports visible/returned counts and truncation, and includes decoded text, author, column, status/progress changes, assignees, and attachment URLs.
• create_amp – Create a new work item (status New). Required: project (key or GUID from get_user_projects), subject, type, priority. Optional: description, url, note, visualSpecLink, linkedWorkItems, parentAmpReference. Response includes reference, projectId, projectKey, projectName, url, etc.
• get_amp_item_with_test_cases – Existing TDD/pen-test-focused subset by ampReference. It requires authenticated access. Prefer get_amp_item plus get_amp_comments for general agent workflows.
• add_amp_update – Team-column update (mirrors Form_EnterComment team fields except assignees/attachments). Required: ampReference plus at least one of message, teamPercentageDone (0–100, step 10), teamProgress (Not started, TDD, Developing, Testing, Done, Blocked), or stage (Test, Local, UAT, Live, Pre-Live). Stage changes post a separate "Done on: {stage}" comment.
• submit_amp_progress_update – Team board: optional teamPercentageDone (0, 10, …, 100) and/or message; at least one required. Omits message when only updating % so AMP can default the comment to "{n}% completed".
• add_amp_test_case_references – ampReference, required testCaseReferences (array of strings), optional message after refs; same as AMP “Update test cases” ([#+REF#] markers).
• submit_pen_test_review – Record a completed Cursor AI pen test review: required ampReference and scope (branch, commits, files, or PR reviewed); optional findings (one per line, or "None"), falsePositives ("N/A" if none), knownRisks ("N/A" if none), summary. Posts a team comment with [#PENTEST:COMPLETE#] and sets review metadata on the work item.
• audit_tdd_amp – Same as above plus auth status message for /audit-tdd-amp flows.
• audit_pen_test_amp – AMP item + pen test review status + test cases, plus auth status message for /run-pen-test flows.

For general agent workflows, call get_amp_item to understand the work item, then get_amp_comments for acceptance details, blockers, and conversation history before using write tools such as add_amp_update.

Cursor command: /run-pen-test

Copy .cursor/commands/run-pen-test.md into your project (or use it from a repo that includes it). The command loads AMP context via MCP, runs a security review, and after human confirmation calls submit_pen_test_review to persist the outcome on AMP.