npm package: @marqa/mcp-server
Description: MCP server for managing the Marqa AI-powered Instagram DM platform
Latest version: 0.1.1

<p align="center">
  <img src="assets/marqa-logo.svg" height="60" alt="Marqa" />
</p>

<h3 align="center">Marqa MCP Server</h3>

<p align="center">
  Manage your AI-powered Instagram DMs from any coding agent.
  <br />
  <a href="https://marqa.ai">Website</a> &middot; <a href="https://docs.marqa.ai">Docs</a> &middot; <a href="https://github.com/marqa-ai/marqa-mcp-server/issues">Issues</a>
</p>

---

The Marqa MCP server connects AI coding agents to your [Marqa](https://marqa.ai) account. Set up brands, train AI agents, manage conversations, and run daily operations — all from your terminal.

Works with Claude Code, Cursor, Windsurf, and any agent that supports the [Model Context Protocol](https://modelcontextprotocol.io).

## Quickstart

The recommended way to get started is the companion skill — it handles MCP configuration and authentication automatically:

```bash
npx skills add marqa-ai/marqa-skill -g
```

Then ask your agent anything: "set up my brand", "check my dashboard", "any handoffs?". The skill configures the MCP server on first use.

### Manual setup

If you prefer to configure the MCP server directly:

**Claude Code** (`.mcp.json` at project root):

```json
{
  "mcpServers": {
    "marqa": {
      "command": "npx",
      "args": ["-y", "@marqa/mcp-server"],
      "env": {}
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "marqa": {
      "command": "npx",
      "args": ["-y", "@marqa/mcp-server"]
    }
  }
}
```

**Windsurf** (`~/.windsurf/mcp_config.json`):

```json
{
  "mcpServers": {
    "marqa": {
      "command": "npx",
      "args": ["-y", "@marqa/mcp-server"]
    }
  }
}
```

Restart your agent after adding the config.

## What you can do

**Set up a brand in one conversation.** Tell your agent "set up my coffee shop on Marqa" and it will create the brand, run an interview to learn about your business, upload your local docs, configure playbooks, and deploy an AI agent — all without leaving your editor.

**Run daily operations.** Ask "how are my brands doing today?" and get a briefing: active conversations, pending handoffs, cooling leads that need re-engagement, and knowledge gaps your agent couldn't answer.

**Manage everything.** 63 tools covering the full Marqa platform:

| Category | Tools | What you can do |
|----------|-------|----------------|
| **Brands** | 7 | Create, configure, delete brands. Scrape websites for knowledge. |
| **Knowledge Base** | 11 | Add FAQs, products, upload documents, review AI recommendations. |
| **Interview** | 5 | Run brand interviews to extract knowledge conversationally. |
| **Agents** | 4 | Create AI agents, configure response speed, assign to accounts. |
| **Voice** | 3 | Analyze brand voice from content, apply fingerprint to agents. |
| **Playbooks** | 8 | Create conversation strategies, toggle system playbooks, get AI help writing them. |
| **Conversations** | 5 | List, filter, update status, trigger deep analysis. |
| **Customers** | 5 | Browse profiles, view session history, set pipeline outcomes. |
| **Operations** | 5 | Dashboard, metrics, cooling leads, handoff queue. |
| **Knowledge Gaps** | 3 | Find what your agent can't answer, resolve gaps in bulk. |
| **Workflows** | 5 | Comment-to-DM automations. Create, test, deploy. |
| **Monitoring** | 2 | Token usage tracking, authentication. |

Plus 3 resources for contextual data and 4 prompt templates for guided workflows (brand setup, daily report, knowledge audit, autonomous monitoring).

## Examples

**Brand setup from local files:**

> "Create a brand called Bloom Coffee. I have product info in `docs/menu.md` and our brand story in `README.md` — upload those to the knowledge base."

Your agent will call `marqa_create_brand`, then `marqa_upload_document` for each file, and suggest next steps.

**Daily operations check:**

> "Check my Marqa dashboard. Any handoffs or cooling leads I should worry about?"

Your agent fetches the dashboard, lists pending handoffs, and shows hot leads that have gone quiet.

**Knowledge gap resolution:**

> "What questions can't my agent answer? Fix the ones you can from our docs."

Your agent calls `marqa_get_topic_clusters`, reads your local files for answers, and uses `marqa_answer_topic_cluster` with `save_to_kb=true` to permanently resolve each gap.

**Playbook creation:**

> "Create a playbook for handling price objections for my premium products."

Your agent uses `marqa_assist_playbook` to get an AI-generated playbook definition, then `marqa_create_playbook` to deploy it.

## Authentication

The server uses OAuth 2.1 with PKCE. Authentication is handled automatically:

1. On first use, `marqa_authenticate` is called — a browser window opens to `app.marqa.ai`
2. You log in and select a workspace
3. Tokens are stored locally at `~/.marqa/credentials.json` (permissions `0600`)
4. On subsequent sessions, `marqa_authenticate` checks your existing credentials instantly — no browser popup, no delay
5. Tokens refresh automatically in the background

No API keys to copy. No environment variables to set.

The server also checks for updates on each session. If a newer version is available on npm, you'll see a notice with upgrade instructions.

## Security

- **OAuth 2.1 + PKCE** — no secrets stored in config files or CLI args
- **Scoped tokens** — request only the permissions you need
- **Local credentials** — stored at `~/.marqa/credentials.json` with `0600` permissions
- **No credential forwarding** — the server authenticates directly with Marqa, never through the agent
- **Destructive operations** — tools that delete data are annotated so agents confirm before executing
- **Rate limiting** — built-in token bucket (100 req/min) prevents runaway loops
- **Sensitive field redaction** — tokens, passwords, and API keys are never written to logs

## Architecture

```
Your AI Agent (Claude Code, Cursor, Windsurf, ...)
       |
       | MCP Protocol (stdio)
       v
  @marqa/mcp-server (runs locally)
  ┌──────────────────────────┐
  │  63 Tools                │
  │  3 Resources             │
  │  4 Prompt Templates      │
  │  OAuth + Token Refresh   │
  │  Response Cache + Limiter│
  │  Auto Update Check       │
  └───────────┬──────────────┘
              | HTTPS
              v
     Marqa API (app.marqa.ai)
```

The server runs as a local subprocess spawned by your agent. It communicates via stdio (JSON-RPC), handles authentication, caches read responses, and formats errors as actionable messages the agent can understand and recover from.

## Environment variables

All optional. The defaults work for most users.

| Variable | Default | Description |
|----------|---------|-------------|
| `MARQA_API_URL` | `https://app.marqa.ai` | Override the API base URL |
| `MARQA_AUTH_URL` | `https://app.marqa.ai` | Override the OAuth server URL |
| `MARQA_CLIENT_ID` | `marqa-mcp-cli` | OAuth client ID |
| `MARQA_LOG_LEVEL` | `info` | Log level (`debug`, `info`, `warn`, `error`) |

## Development

```bash
git clone https://github.com/marqa-ai/marqa-mcp-server.git
cd marqa-mcp-server
npm install
npm run dev    # Watch mode with tsx
npm test       # 294 tests
npm run build  # TypeScript compile
```

## Contributing

We welcome contributions. Please open an issue first to discuss what you'd like to change.

## License

MIT