# apichai-17/meta-mcp architecture

> Architecture diagram of the GitHub repository apichai-17/meta-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apichai-17/meta-mcp
- Repository: https://github.com/apichai-17/meta-mcp

## Overview

Meta Ads MCP Server exposes Meta Marketing API operations to AI clients through MCP, with both local stdio and documented remote OAuth deployment modes. The main workflow is client request → MCP tool/resource handling → authenticated Meta API request → advertising data or action returned. Campaign/ad setup, audience targeting, creative work, and analytics remain distinct product stages. Source excerpts confirm the stdio entry point, resource registration, API-client request path, and authentication/storage behavior; some tool-to-client and remote-handler wiring is inferred only from the documented capabilities and tree.

Main entry points: [`src/meta-client.ts`](https://github.com/apichai-17/meta-mcp/blob/main/src/meta-client.ts) (Marketing API client), [`src/index.ts`](https://github.com/apichai-17/meta-mcp/blob/main/src/index.ts) (Local MCP server), [`api/mcp.ts`](https://github.com/apichai-17/meta-mcp/blob/main/api/mcp.ts) (Remote MCP endpoint), [`src/utils/user-auth.ts`](https://github.com/apichai-17/meta-mcp/blob/main/src/utils/user-auth.ts) (User sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP interface"]
  node_stdio["Local MCP server<br/>[index.ts]"]
  node_campaign_resources["Campaign resources<br/>[campaigns.ts]"]
  node_insights_resources["Insights resources<br/>[insights.ts]"]
  node_audience_resources["Audience resources<br/>[audiences.ts]"]
end

subgraph group_ads["Advertising capabilities"]
  node_campaign_tools["Campaign and ads<br/>[campaigns.ts]"]
  node_analytics_tools["Analytics tools<br/>[analytics.ts]"]
  node_audience_tools["Audience tools<br/>[audiences.ts]"]
  node_creative_tools["Creative tools<br/>[creatives.ts]"]
  node_meta_client["Marketing API client<br/>[meta-client.ts]"]
end

subgraph group_identity["Identity and resilience"]
  node_oauth_tools["OAuth tools<br/>[oauth.ts]"]
  node_auth_manager["Token management<br/>[auth.ts]"]
  node_user_auth["User sessions<br/>[user-auth.ts]"]
  node_session_store[("Session storage<br/>[user-auth.ts]")]
  node_error_handler["API error handling<br/>[error-handler.ts]"]
  node_rate_limiter["Rate limiting<br/>[rate-limiter.ts]"]
  node_pagination["Pagination<br/>[pagination.ts]"]
end

subgraph group_web["Remote access"]
  node_api_mcp["Remote MCP endpoint<br/>[mcp.ts]"]
  node_oauth_routes["OAuth routes"]
end

node_assistant(("AI assistant"))
node_meta_api["Meta Marketing API"]

node_assistant -->|"sends MCP requests"| node_stdio
node_assistant -.->|"sends remote requests"| node_api_mcp
node_stdio -->|"registers tools"| node_campaign_tools
node_stdio -->|"registers tools"| node_analytics_tools
node_stdio -->|"registers tools"| node_audience_tools
node_stdio -->|"registers tools"| node_creative_tools
node_stdio -->|"registers tools"| node_oauth_tools
node_stdio -->|"registers resources"| node_campaign_resources
node_stdio -->|"registers resources"| node_insights_resources
node_stdio -->|"registers resources"| node_audience_resources
node_campaign_resources -->|"fetches campaign data"| node_meta_client
node_audience_resources -->|"fetches audience data"| node_meta_client
node_campaign_tools -->|"manages ads"| node_meta_client
node_analytics_tools -->|"requests insights"| node_meta_client
node_audience_tools -->|"manages audiences"| node_meta_client
node_creative_tools -->|"manages creatives"| node_meta_client
node_oauth_tools -->|"manages tokens"| node_auth_manager
node_meta_client -->|"uses credentials"| node_auth_manager
node_meta_client -->|"limits requests"| node_rate_limiter
node_meta_client -->|"handles responses"| node_error_handler
node_meta_client -->|"parses pages"| node_pagination
node_meta_client -->|"sends API requests"| node_meta_api
node_api_mcp -->|"authenticates users"| node_user_auth
node_api_mcp -->|"dispatches MCP tools"| node_campaign_tools
node_api_mcp -->|"dispatches MCP tools"| node_analytics_tools
node_api_mcp -->|"dispatches MCP tools"| node_audience_tools
node_api_mcp -->|"dispatches MCP tools"| node_creative_tools
node_oauth_routes -->|"manages sessions"| node_user_auth
node_user_auth -->|"reads and writes"| node_session_store
node_user_auth -->|"builds user credentials"| node_auth_manager

click node_stdio "https://github.com/apichai-17/meta-mcp/blob/main/src/index.ts"
click node_api_mcp "https://github.com/apichai-17/meta-mcp/blob/main/api/mcp.ts"
click node_campaign_tools "https://github.com/apichai-17/meta-mcp/blob/main/src/tools/campaigns.ts"
click node_analytics_tools "https://github.com/apichai-17/meta-mcp/blob/main/src/tools/analytics.ts"
click node_audience_tools "https://github.com/apichai-17/meta-mcp/blob/main/src/tools/audiences.ts"
click node_creative_tools "https://github.com/apichai-17/meta-mcp/blob/main/src/tools/creatives.ts"
click node_oauth_tools "https://github.com/apichai-17/meta-mcp/blob/main/src/tools/oauth.ts"
click node_campaign_resources "https://github.com/apichai-17/meta-mcp/blob/main/src/resources/campaigns.ts"
click node_insights_resources "https://github.com/apichai-17/meta-mcp/blob/main/src/resources/insights.ts"
click node_audience_resources "https://github.com/apichai-17/meta-mcp/blob/main/src/resources/audiences.ts"
click node_meta_client "https://github.com/apichai-17/meta-mcp/blob/main/src/meta-client.ts"
click node_auth_manager "https://github.com/apichai-17/meta-mcp/blob/main/src/utils/auth.ts"
click node_user_auth "https://github.com/apichai-17/meta-mcp/blob/main/src/utils/user-auth.ts"
click node_session_store "https://github.com/apichai-17/meta-mcp/blob/main/src/utils/user-auth.ts"
click node_oauth_routes "https://github.com/apichai-17/meta-mcp/tree/main/api/auth"
click node_error_handler "https://github.com/apichai-17/meta-mcp/blob/main/src/utils/error-handler.ts"
click node_rate_limiter "https://github.com/apichai-17/meta-mcp/blob/main/src/utils/rate-limiter.ts"
click node_pagination "https://github.com/apichai-17/meta-mcp/blob/main/src/utils/pagination.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stdio,node_campaign_resources,node_insights_resources,node_audience_resources toneBlue
class node_campaign_tools,node_analytics_tools,node_audience_tools,node_creative_tools,node_meta_client toneAmber
class node_oauth_tools,node_auth_manager,node_user_auth,node_session_store,node_error_handler,node_rate_limiter,node_pagination,node_meta_api toneMint
class node_api_mcp,node_oauth_routes toneRose
class node_assistant toneIndigo
```

## Components

### MCP interface

- [Local MCP server](https://github.com/apichai-17/meta-mcp/blob/main/src/index.ts): `src/index.ts`
- [Campaign resources](https://github.com/apichai-17/meta-mcp/blob/main/src/resources/campaigns.ts): `src/resources/campaigns.ts`
- [Insights resources](https://github.com/apichai-17/meta-mcp/blob/main/src/resources/insights.ts): `src/resources/insights.ts`
- [Audience resources](https://github.com/apichai-17/meta-mcp/blob/main/src/resources/audiences.ts): `src/resources/audiences.ts`

### Advertising capabilities

- [Campaign and ads](https://github.com/apichai-17/meta-mcp/blob/main/src/tools/campaigns.ts): `src/tools/campaigns.ts`
- [Analytics tools](https://github.com/apichai-17/meta-mcp/blob/main/src/tools/analytics.ts): `src/tools/analytics.ts`
- [Audience tools](https://github.com/apichai-17/meta-mcp/blob/main/src/tools/audiences.ts): `src/tools/audiences.ts`
- [Creative tools](https://github.com/apichai-17/meta-mcp/blob/main/src/tools/creatives.ts): `src/tools/creatives.ts`
- [Marketing API client](https://github.com/apichai-17/meta-mcp/blob/main/src/meta-client.ts): `src/meta-client.ts`

### Identity and resilience

- [OAuth tools](https://github.com/apichai-17/meta-mcp/blob/main/src/tools/oauth.ts): `src/tools/oauth.ts`
- [Token management](https://github.com/apichai-17/meta-mcp/blob/main/src/utils/auth.ts): `src/utils/auth.ts`
- [User sessions](https://github.com/apichai-17/meta-mcp/blob/main/src/utils/user-auth.ts): `src/utils/user-auth.ts`
- [Session storage](https://github.com/apichai-17/meta-mcp/blob/main/src/utils/user-auth.ts): `src/utils/user-auth.ts`
- [API error handling](https://github.com/apichai-17/meta-mcp/blob/main/src/utils/error-handler.ts): `src/utils/error-handler.ts`
- [Rate limiting](https://github.com/apichai-17/meta-mcp/blob/main/src/utils/rate-limiter.ts): `src/utils/rate-limiter.ts`
- [Pagination](https://github.com/apichai-17/meta-mcp/blob/main/src/utils/pagination.ts): `src/utils/pagination.ts`

### Remote access

- [Remote MCP endpoint](https://github.com/apichai-17/meta-mcp/blob/main/api/mcp.ts): `api/mcp.ts`
- [OAuth routes](https://github.com/apichai-17/meta-mcp/tree/main/api/auth): `api/auth`

### Other components

- **AI assistant**
- **Meta Marketing API**

## Connections

- AI assistant → Local MCP server: sends MCP requests
- AI assistant → Remote MCP endpoint: sends remote requests
- Local MCP server → Campaign and ads: registers tools
- Local MCP server → Analytics tools: registers tools
- Local MCP server → Audience tools: registers tools
- Local MCP server → Creative tools: registers tools
- Local MCP server → OAuth tools: registers tools
- Local MCP server → Campaign resources: registers resources
- Local MCP server → Insights resources: registers resources
- Local MCP server → Audience resources: registers resources
- Campaign resources → Marketing API client: fetches campaign data
- Audience resources → Marketing API client: fetches audience data
- Campaign and ads → Marketing API client: manages ads
- Analytics tools → Marketing API client: requests insights
- Audience tools → Marketing API client: manages audiences
- Creative tools → Marketing API client: manages creatives
- OAuth tools → Token management: manages tokens
- Marketing API client → Token management: uses credentials
- Marketing API client → Rate limiting: limits requests
- Marketing API client → API error handling: handles responses
- Marketing API client → Pagination: parses pages
- Marketing API client → Meta Marketing API: sends API requests
- Remote MCP endpoint → User sessions: authenticates users
- Remote MCP endpoint → Campaign and ads: dispatches MCP tools
- Remote MCP endpoint → Analytics tools: dispatches MCP tools
- Remote MCP endpoint → Audience tools: dispatches MCP tools
- Remote MCP endpoint → Creative tools: dispatches MCP tools
- OAuth routes → User sessions: manages sessions
- User sessions → Session storage: reads and writes
- User sessions → Token management: builds user credentials