Skip to main content
Glama
mcp-server-peecai

mcp-server-peecai

by thein-art

Note: This is an unofficial community project, not affiliated with or endorsed by Peec AI. It requires a Peec AI account and API key.

API Beta: The Peec AI API is currently in beta — endpoints, payloads, and responses may change. Access is limited to Enterprise customers.


What it does

Peec AI tracks how brands appear in AI-generated answers. This MCP server gives any MCP-compatible client direct access to that data — 38 tools covering projects, brands, prompts, chats, query analysis, analytics reports, source content, brand profiles, and full CRUD operations.

Key capabilities:

  • Query brand visibility, sentiment, and position across AI models

  • Analyze which domains and URLs get cited in AI responses

  • Inspect individual chat interactions with full source attribution

  • Slice data by model, prompt, category tag, topic, country, or date

  • Create, update, and delete brands, prompts, tags, and topics (opt-in)

  • Review and act on AI-generated prompt and topic suggestions

Related MCP server: ai-visibility-mcp

Quick Start

1. Get your API key

Sign up at app.peec.ai and create an API key under Settings > API Keys.

2. Configure

claude mcp add --transport stdio peecai -- npx -y mcp-server-peecai

Set environment variables:

export PEECAI_API_KEY="your-api-key"
export PEECAI_PROJECT_ID="your-project-id"  # optional default

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "peecai": {
      "command": "npx",
      "args": ["-y", "mcp-server-peecai"],
      "env": {
        "PEECAI_API_KEY": "your-api-key",
        "PEECAI_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "peecai": {
      "command": "npx",
      "args": ["-y", "mcp-server-peecai"],
      "env": {
        "PEECAI_API_KEY": "your-api-key",
        "PEECAI_PROJECT_ID": "your-project-id"
      }
    }
  }
}

3. Verify

Confirm the peecai server is connected — in Claude Code run /mcp, in VS Code/Cursor check the MCP server status in the output panel.

Tools

Data Retrieval (19 tools)

list_projects — List all projects for the company.

  • Returns: project IDs, names, statuses (CUSTOMER = active, PITCH = demo)

  • Parameters: limit, offset

list_brands — List tracked brands with their associated domains.

  • Parameters: project_id, limit, offset

list_prompts — List monitored search prompts.

  • Returns: prompt messages, tags, topics, user location, search volume

  • Parameters: project_id, topic_id, tag_id, limit, offset

list_tags — List category tags for a project.

  • Parameters: project_id, limit, offset

list_topics — List topic groupings for a project.

  • Parameters: project_id, limit, offset

list_models — Deprecated; prefer list_model_channels. List tracked AI models (ChatGPT, Perplexity, etc.).

  • Returns: model IDs and active status

  • Parameters: project_id, limit, offset

list_model_channels — List model channels (stable IDs grouping one or more models, e.g. openai-0, perplexity-0).

  • Returns: channel ID, description, currently active model, active status

  • Parameters: project_id, limit, offset

list_chats — List AI chat interactions with optional date and dimension filtering.

  • Returns: chat IDs, prompt/model/model_channel refs, dates

  • Parameters: project_id, start_date, end_date, brand_id, prompt_id, model_id, model_channel_id, limit, offset

get_chat_content — Get full content of a specific chat.

  • Returns: sources (URLs, domains, citation counts), brands mentioned, messages, queries, products

  • Parameters: chat_id, project_id

list_prompt_suggestions — List AI-generated prompt suggestions.

  • Parameters: project_id, topic_id, limit, offset

list_topic_suggestions — List AI-generated topic suggestions.

  • Parameters: project_id, limit, offset

list_brand_suggestions — List AI-generated brand suggestions.

  • Returns: suggestion ID, name, domains, chat_count

  • Parameters: project_id, limit, offset

get_project_profile — Read the project's brand profile (occupation, industry, brand identity, target markets, audience distribution).

  • Returns: profile object or null if not yet profiled

  • Parameters: project_id

Analytics Reports

All report tools support dimensions for multi-level breakdowns: prompt_id, model_id, model_channel_id, tag_id, topic_id, date, country_code, chat_id. Date filtering via start_date / end_date (YYYY-MM-DD). Server-side filtering via filters parameter (field, operator: "in" | "not_in", values).

get_brands_report — Brand analytics per brand.

Metric

Description

visibility

Ratio 0–1 (visibility_count / visibility_total)

sentiment

Score 0–100, 50 = neutral

position

Average rank when mentioned, lower = better

share_of_voice

Share of voice 0–1 (proportion of total mentions)

mention_count

Number of times the brand was mentioned

get_domains_report — Domain-level analytics.

Metric

Description

retrieval_rate

Share of chats retrieving this domain (0–1)

citation_rate

Average citations per retrieval

classification

OWN, CORPORATE, COMPETITOR, RELATED, EDITORIAL, REFERENCE, INSTITUTIONAL, UGC, OTHER

get_urls_report — URL-level analytics.

Metric

Description

retrieval_count

Number of chats retrieving this URL (replaces deprecated retrievals)

citation_count

Total citations across all chats

citation_rate

Average citations per retrieval

classification

HOMEPAGE, PRODUCT_PAGE, CATEGORY_PAGE, LISTICLE, COMPARISON, ARTICLE, HOW_TO_GUIDE, PROFILE, ALTERNATIVE, DISCUSSION, OTHER

get_url_content — Get the scraped markdown content of a source URL discovered via get_urls_report.

  • Returns: content (markdown, null while scraping pending), title, domain, channel_title, classification, url_classification, content_length, truncated, content_updated_at

  • Parameters: url, project_id, max_length (1–20,000,000, default 100,000)

  • If stored content exceeds max_length, truncated=true — re-request with a larger max_length to get more.

Query Analysis

search_queries — Get search queries AI models generated when answering prompts.

  • Parameters: project_id, start_date, end_date, filters, limit, offset

shopping_queries — Get shopping/product queries AI models generated.

  • Parameters: project_id, start_date, end_date, filters, limit, offset

Write Operations (19 tools, opt-in)

Write tools are disabled by default for safety. Enable them by setting PEECAI_ALLOW_WRITES=true.

When disabled, these tools are completely invisible — they don't appear in tools/list and cannot be called by any client.

Entity

Create

Update

Delete

Brands

create_brand

update_brand

delete_brand

Prompts

create_prompt

update_prompt

delete_prompt

Tags

create_tag

update_tag

delete_tag

Topics

create_topic

update_topic

delete_topic

Suggestions

Accept

Reject

Prompt suggestions

accept_prompt_suggestion

reject_prompt_suggestion

Topic suggestions

accept_topic_suggestion

reject_topic_suggestion

Brand suggestions

accept_brand_suggestion

reject_brand_suggestion

set_project_profile — Replace the project's brand profile (occupation, industry, brand identity, target markets, audience distribution). Full overwrite; audienceDistribution percentages must sum to 100. Triggers a background refresh of prompt suggestions.

Delete operations are soft-deletes and irreversible through the API. Delete tools carry destructiveHint: true in their MCP annotations, causing clients like Claude Code to require explicit user approval before execution.

Tool Annotations

Tool type

Read-only

Idempotent

Destructive

All read tools (19)

Yes

Yes

No

Create (4)

No

No

No

Update (4)

No

Yes

No

Delete (4)

No

Yes

Yes

Accept suggestion (3)

No

No

No

Reject suggestion (3)

No

Yes

No

set_project_profile (1)

No

Yes

Yes

Resources

MCP resources provide reference data that clients can fetch without a tool call.

Resource

Type

Description

peecai://projects

Static

List all projects

peecai://projects/{project_id}/brands

Template

Brands for a project

peecai://projects/{project_id}/tags

Template

Tags for a project

peecai://projects/{project_id}/topics

Template

Topics for a project

peecai://projects/{project_id}/models

Template

AI models for a project

peecai://projects/{project_id}/prompts

Template

Prompts for a project

Resource templates support listing — clients can enumerate available resources across all projects.

Prompt Templates

Guided analytical workflows available as MCP prompts. All prompts support project_id autocompletion.

Prompt

Description

brand-visibility-analysis

Analyze brand visibility, sentiment, and position across AI models

competitive-gap-analysis

Compare own brand vs competitors across prompts and models

ai-search-citation-report

Analyze domain and URL citations in AI responses

Example Prompts

"List my Peec AI projects"
"Show brand visibility for the last 30 days"
"Which domains get cited most in AI search results?"
"Compare brand sentiment across ChatGPT and Perplexity"
"Show me the full chat content for chat ID abc-123"
"Get URL report broken down by AI model and country"
"What search queries do AI models use when answering my prompts?"
"Create a brand 'My Brand' with domain mybrand.com"
"Add a new prompt: 'best CRM software 2025' for country DE"

Environment Variables

Variable

Required

Description

PEECAI_API_KEY

Yes

API key from app.peec.ai

PEECAI_PROJECT_ID

No

Default project ID — saves repeating it in every tool call

PEECAI_ALLOW_WRITES

No

Set to true to enable write operations (create/update/delete). Disabled by default for safety.

MCP Protocol Features

This server implements the MCP 2025-11-25 specification:

  • Structured content — list tools return structuredContent alongside text for type-safe client parsing

  • Tool annotations — readOnlyHint, destructiveHint, idempotentHint on every tool

  • Progress notifications — report tools send progress updates when the client provides a progressToken

  • Structured logging — API errors are sent as MCP log notifications with endpoint, status, and message context

  • Prompt completions — project_id argument supports autocompletion via completable()

  • Resource templates — with list callbacks for enumerating resources across projects

  • Cancellation support — all tools forward the MCP AbortSignal to API calls

API Drift Detection

The Peec AI API is in beta and may change. A drift detection script compares the live OpenAPI spec against a committed snapshot:

npm run check:api-drift
  • No drift: exit code 0, snapshot is current

  • Drift detected: exit code 1, shows a diff of changes

No API key is required — the OpenAPI spec is publicly accessible.

Development

Prerequisites

  • Node.js >= 22

  • npm

Commands

npm install              # Install dependencies
npm run build            # Compile TypeScript to dist/
npm run dev              # Watch mode — recompile on changes
npm test                 # Run unit tests (372 tests)
npm run test:watch       # Run tests in watch mode
npm run test:integration # Run integration tests (requires PEECAI_API_KEY)
npm run check:api-drift  # Check for API spec changes

Integration Tests

Integration tests hit the live Peec AI API and are skipped by default in npm test.

# Read-only smoke test (all 19 read tools + prompts + resources)
PEECAI_API_KEY=xxx npm run test:integration

# Full CRUD round-trip (requires a test project + write access)
PEECAI_ALLOW_WRITES=true PEECAI_TEST_PROJECT_ID=or_xxx npm run test:integration

Project Structure

src/
├── index.ts              # Server entry point, tool/resource/prompt registration
├── api-client.ts         # HTTP client for Peec AI Customer API
├── types.ts              # TypeScript interfaces for API responses
├── schemas.ts            # Zod output schemas for structured content
├── util.ts               # Validation, date handling, MCP response helpers
├── prompts.ts            # MCP prompt templates (guided workflows)
└── tools/                # One file per MCP tool (or tool group)
    ├── projects.ts       # list_projects
    ├── brands.ts         # list_brands
    ├── prompts.ts        # list_prompts
    ├── tags.ts           # list_tags
    ├── topics.ts         # list_topics
    ├── models.ts         # list_models
    ├── model-channels.ts # list_model_channels
    ├── chats.ts          # list_chats
    ├── chat-content.ts   # get_chat_content
    ├── prompt-suggestions.ts  # list_prompt_suggestions
    ├── topic-suggestions.ts   # list_topic_suggestions
    ├── brand-suggestions.ts   # list_brand_suggestions
    ├── project-profile.ts # get_project_profile, set_project_profile
    ├── report-brands.ts  # get_brands_report
    ├── report-domains.ts # get_domains_report
    ├── report-urls.ts    # get_urls_report
    ├── url-content.ts    # get_url_content
    ├── queries-search.ts # search_queries
    ├── queries-shopping.ts    # shopping_queries
    ├── write-brands.ts   # create/update/delete brand
    ├── write-prompts.ts  # create/update/delete prompt
    ├── write-tags.ts     # create/update/delete tag
    ├── write-topics.ts   # create/update/delete topic
    └── suggestion-actions.ts  # accept/reject suggestions

License

MIT


Built by Tobias Hein at artaxo — a digital marketing agency specializing in AI Search Optimization.

Available Tools

17 tools
get_brands_reportBrand Visibility ReportA
Read-onlyIdempotent

Get brand analytics report per brand. Metrics: visibility (visibility_count/visibility_total), share_of_voice (0-1), mention_count, sentiment (0-100 scale, 50=neutral), position (avg rank when mentioned, lower=better). Returns up to limit results (default: 100). Use brand_id shortcut or filters array for server-side filtering. Supports date filtering and dimensional breakdowns. Without date filters, returns data across all available dates. Empty results may indicate the project has no report data for the given time range or filters — try a broader date range or fewer filters.

Inputs: project_id, start_date, end_date, dimensions, +4 more.

get_chat_contentGet Chat ContentA
Read-onlyIdempotent

Get full content of a specific AI chat. Returns sources, brands mentioned, messages, queries, and products.

Inputs: chat_id (required), project_id. Returns: _summary, chat

get_domains_reportDomain Citation ReportA
Read-onlyIdempotent

Get domain analytics report: retrieval_rate, citation_rate, and retrieved_percentage. Classification values: OWN, CORPORATE, COMPETITOR, EDITORIAL, REFERENCE, INSTITUTIONAL, UGC, OTHER. Returns up to limit results (default: 100). Classification is filtered client-side after retrieval. Use filters array for server-side filtering by model, tag, topic, prompt, domain, URL, or country_code. Without date filters, returns data across all available dates. Empty results may indicate the project has no report data for the given time range or filters.

Inputs: project_id, start_date, end_date, dimensions, +4 more.

get_url_contentGet URL ContentA
Read-onlyIdempotent

Get the scraped markdown content of a source URL. Use the URLs report (get_urls_report) to discover URLs. Returns markdown content plus metadata (title, domain, channel_title, classification, url_classification, content_length, truncated, content_updated_at). If stored content exceeds max_length, the response is truncated and truncated=true — re-request with a larger max_length to get more. Returns 404 if the URL is not tracked by the project.

Inputs: url (required), project_id, max_length. Returns: _summary, content

get_urls_reportURL Citation ReportA
Read-onlyIdempotent

Get URL analytics report: citation_count (total citations), retrievals (retrieval count), citation_rate. Classification values: HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, OTHER. Returns up to limit results (default: 100). Classification is filtered client-side after retrieval. Use filters array for server-side filtering by model, tag, topic, prompt, domain, URL, or country_code. Without date filters, returns data across all available dates. Empty results may indicate the project has no report data for the given time range or filters.

Inputs: project_id, start_date, end_date, dimensions, +4 more.

list_brandsList BrandsA
Read-onlyIdempotent

List tracked brands for a Peec AI project. Returns brand IDs, names, and associated domains.

Inputs: project_id, limit, offset. Returns: _summary, brands

list_chatsList ChatsA
Read-onlyIdempotent

List AI chat interactions tracked by Peec AI. Returns up to limit results (default: 100). Recommended: use date filters to scope results. Returns chat IDs, prompt/model refs, and dates. Without date filters, returns all chats.

Inputs: project_id, start_date, end_date, brand_id, +5 more. Returns: _summary, chats

list_model_channelsList Model ChannelsA
Read-onlyIdempotent

List model channels tracked by Peec AI. A model channel (e.g. openai-0, perplexity-0) is a stable identifier that groups one or more underlying models, so the channel ID remains constant even when the underlying model is rotated. Returns channel IDs, descriptions, the currently active model, and active status.

Inputs: project_id, limit, offset. Returns: _summary, model_channels

list_modelsList AI ModelsA
Read-onlyIdempotent

List AI models tracked by Peec AI (ChatGPT, Perplexity, etc.). Returns model IDs and active status.

Inputs: project_id, limit, offset. Returns: _summary, models

list_projectsList ProjectsA
Read-onlyIdempotent

List all Peec AI projects for the company. Returns project IDs, names, and statuses. Status values: CUSTOMER (active, ongoing monitoring), CUSTOMER_ENDED, PITCH (active demo), PITCH_ENDED (completed demo), TRIAL, TRIAL_ENDED, ONBOARDING, DELETED. Use CUSTOMER projects for current data.

Inputs: limit, offset. Returns: _summary, projects

list_promptsList PromptsA
Read-onlyIdempotent

List search prompts for a Peec AI project. Returns prompt IDs, messages, tags, topics, locations, and search volume.

Inputs: project_id, topic_id, tag_id, limit, +1 more. Returns: _summary, prompts

list_prompt_suggestionsList Prompt SuggestionsA
Read-onlyIdempotent

List suggested prompts for a Peec AI project. Suggestions can be accepted to create prompts or rejected to dismiss them.

Inputs: project_id, topic_id, limit, offset. Returns: _summary, prompt_suggestions

list_tagsList TagsA
Read-onlyIdempotent

List category tags for a Peec AI project. Returns tag IDs and names.

Inputs: project_id, limit, offset. Returns: _summary, tags

list_topicsList TopicsA
Read-onlyIdempotent

List topic groupings for a Peec AI project. Returns topic IDs and names.

Inputs: project_id, limit, offset. Returns: _summary, topics

list_topic_suggestionsList Topic SuggestionsA
Read-onlyIdempotent

List suggested topics for a Peec AI project. Suggestions can be accepted to create topics or rejected to dismiss them.

Inputs: project_id, limit, offset. Returns: _summary, topic_suggestions

search_queriesSearch QueriesA
Read-onlyIdempotent

Get search queries that AI models generated when answering prompts. Returns the actual search queries models used to find information. Useful for understanding how AI models research topics. Without date filters, returns data across all available dates. Empty results may indicate the project has no query data for the given time range or filters.

Inputs: project_id, start_date, end_date, filters, +2 more.

shopping_queriesShopping QueriesA
Read-onlyIdempotent

Get shopping/product queries that AI models generated when answering prompts. Returns product-related queries with associated product names. Useful for understanding product recommendations by AI models. Without date filters, returns data across all available dates. Empty results may indicate the project has no query data for the given time range or filters.

Inputs: project_id, start_date, end_date, filters, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing entities (brands, chats, models, etc.) vs. retrieving reports (brands, domains, URLs) vs. fetching content. No overlapping functionality, and descriptions clarify any potential confusion.

    Naming Consistency4/5

    The majority follow a consistent verb_noun pattern (list_*, get_*). The only deviation is 'shopping_queries' which uses noun_noun, but it still clearly indicates its purpose. Overall pattern is predictable.

    Tool Count5/5

    17 tools is appropriate for an AI analytics platform covering listing, reporting, and query retrieval. Each tool serves a specific need without redundancy, fitting well within the 3-15 range plus a few extras.

    Completeness5/5

    The tool set covers all essential operations for the domain: listing all tracked entities, retrieving detailed reports and content, and searching queries. There are no obvious missing features for a read-only analytics monitoring server.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables brand visibility monitoring across major AI platforms like ChatGPT, Claude, Gemini, and Perplexity. It allows users to track visibility scores, analyze competitor data, and receive actionable insights to improve AI-generated brand recommendations.
      16
      11 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      AI search intelligence + Ahrefs-class SEO suite as 59 MCP tools. Track your brand across ChatGPT, Google AI Overview, Gemini, Claude, and Perplexity with persona-anchored Brand Radar dispatches.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Monitors brand mentions, citations, sentiment, competitor share of voice, and GEO performance across AI search engines.
      1
      MIT

    Appeared in Searches