Tranna MCP

Tranna MCP is a production-oriented Model Context Protocol (MCP) server foundation for connecting Claude Desktop to future social-media and marketing platforms.

It provides a reusable connector framework, one disabled-by-default fake ExampleConnector, and optional Meta and Google connectors that call only official APIs. The Google connector supports GA4, Google Ads, Business Profile, Search Console, and YouTube Data/Analytics through one OAuth consent flow. The server always exposes the read-only diagnostic tool tranna_get_service_status.

Start with Docker Compose

From this directory, run:

docker compose up

Docker Compose builds the image if needed and starts the server. The health endpoints are available at:

• http://localhost:3000/healthz — process liveness
• http://localhost:3000/readyz — MCP server readiness

Stop it with Ctrl+C, then run docker compose down if you also want to remove the container and network.

For configuration and Claude Desktop connection instructions, see SETUP.md.

Architecture

src/
├── authentication/  # Application authentication contracts; disabled placeholder only
├── configuration/   # Validated environment configuration
├── connectors/      # Reusable OAuth connector framework, registry, and fake example
├── server/          # MCP lifecycle, stdio transport, health server, state
├── tools/           # MCP tool registration and tool implementations
└── utilities/       # Structured logger and shared errors

The only transport enabled is the official MCP SDK's stdio transport, which is the normal local transport for Claude Desktop. Operational logs are written to stderr, leaving stdout exclusively for MCP JSON-RPC messages.

Configuration

Copy .env.example to .env to adjust local Docker Compose settings. All values are validated at startup.

Variable	Default	Purpose
NODE_ENV	production in Docker	development, test, or production
LOG_LEVEL	info	debug, info, warn, or error
SERVICE_VERSION	0.1.0	Version returned in server status
HEALTH_ENABLED	true	Enables the health HTTP server
HEALTH_HOST	0.0.0.0	Interface for health checks
HEALTH_PORT	3000	Health HTTP port for native execution
HOST_HEALTH_PORT	3000	Host port mapped by Docker Compose
EXAMPLE_CONNECTOR_ENABLED	false	Enables the fake demonstration connector and its fake-data MCP tool
META_CONNECTOR_ENABLED	false	Enables the real Meta connector after all required META_* values are supplied
GOOGLE_CONNECTOR_ENABLED	false	Enables the real Google connector after all required GOOGLE_* OAuth settings are supplied

docker-compose.yml intentionally fixes the container health port to 3000, because Docker's health check runs inside the container. Use HOST_HEALTH_PORT to change the host-facing port. Do not set HEALTH_ENABLED=false for the Compose service, because its health check requires the endpoint.

Development and verification

Requires Node.js 24 or later.

npm install
npm run typecheck
npm test
npm run build
npm start

Use npm run dev for file-watching development. It loads .env when present.

Meta connector

The Meta connector is disabled by default. When explicitly configured, it supports official Graph API access to Facebook Pages, linked Instagram professional accounts, and Marketing API campaign operations. OAuth credentials, Page access tokens, OAuth state, and discovered asset IDs are encrypted at rest with AES-256-GCM; tokens are never written to application logs or MCP tool output.

Read the detailed Meta setup guide before enabling it. The guide covers app creation, products, OAuth redirect settings, permissions, review/business-verification limits, all environment variables, the connection flow, and supported limitations.

META_ALLOW_WRITE_OPERATIONS defaults to false. Publishing, campaign creation, campaign state changes, and budget updates fail locally until it is explicitly set to true.

Google connector

The Google connector is disabled by default. It uses Google's OAuth authorization-code flow and encrypts OAuth tokens and CSRF state at rest with AES-256-GCM. One google_begin_connect / google_complete_connect authorization requests the configured GA4, Google Ads, Business Profile, Search Console, and YouTube scopes. Tokens and authorization codes are never logged or returned by MCP tools.

Set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_TOKEN_ENCRYPTION_KEY, GOOGLE_ADS_DEVELOPER_TOKEN, and a currently supported GOOGLE_ADS_API_VERSION, then register the exact callback URI http://localhost:3000/oauth/google/callback. Enable the listed APIs in the Google Cloud project. GOOGLE_ADS_LOGIN_CUSTOMER_ID is optional and supports manager-account access. The connector sends transient 429/5xx failures through a bounded exponential retry policy.

GOOGLE_ALLOW_WRITE_OPERATIONS defaults to false. Review replies and YouTube uploads are locally rejected until it is explicitly enabled. update_video_metadata and delete_video are registered only when GOOGLE_OAUTH_SCOPES explicitly includes https://www.googleapis.com/auth/youtube.force-ssl. publish_short uploads content marked with #Shorts; YouTube makes the final Shorts eligibility determination.

The Google connector exposes direct provider operations only: OAuth lifecycle, GA4 accounts/properties/reports, Google Ads accounts/campaigns/metrics, Business Profile locations/reviews, Search Console sites/query/page rows, and supported YouTube data, analytics, and upload operations. Google Ads campaign tools are named list_google_ads_campaigns and get_google_ads_campaign to avoid collisions with Meta campaign tools. It intentionally has no recommendation, anomaly-detection, marketing-dashboard, or other marketing-intelligence layer.

Required Google Cloud APIs are Google Analytics Admin API, Google Analytics Data API, Google Ads API, Business Profile Account Management API, Business Profile Business Information API, Google My Business API (reviews), Search Console API, YouTube Data API v3, and YouTube Analytics API. The default scopes are openid, email, profile, Analytics read-only, Ads, Business Profile, Search Console read-only, and YouTube read-only/upload; .env.example contains each official scope URL. Add https://www.googleapis.com/auth/youtube.force-ssl only when video metadata update and deletion are needed.

Current scope and platform limitations

The ExampleConnector remains a framework demonstration only: its OAuth client, token values, health check, capability, and MCP tool all use fixed local fake data and make no network calls. Meta and Google are the real platform connectors.

When adding a connector, use only the platform's documented official API and SDK, implement only approved scopes/capabilities, and document any access tier, app review, business verification, sandbox restriction, or unavailable capability. This project intentionally provides no unofficial API clients or web-scraping fallback.

Connector framework

Every connector extends AbstractConnector and receives its dependencies through the constructor. The base class provides a uniform interface and implements configuration gating, lifecycle state, OAuth token persistence/refresh, health tracking, safe status snapshots, structured logging, and error conversion. It does not make provider calls itself.

Method	Purpose
connect()	Runs the injected OAuth authorization flow and stores its returned token.
disconnect()	Optionally revokes the token through the injected OAuth client and clears local storage.
refreshToken()	Loads and refreshes a stored OAuth token without exposing it to MCP.
health()	Runs the connector-specific health check and returns a normalized result.
status()	Returns a token-free connection and configuration snapshot.
capabilities()	Lists provider features and documented limitations.
registerTools()	Registers connector MCP tools through a testable, narrow tool-registry boundary.

src/connectors/connector-registration.ts is the automatic registration composition point. It creates each known connector using the application configuration and dependency injection. Disabled connectors remain visible in service status but do not register MCP tools and reject connection attempts.

Creating a future connector

1. Confirm the exact official API capability, required OAuth scopes, approval requirements, and business-verification requirements.
2. Create a connector class under src/connectors/<connector-name>/ that extends AbstractConnector.
3. Inject an official OAuth client, a secure production token store, logger, and connector configuration. Do not construct these inside the connector class.
4. Implement oauthScopes, performHealthCheck, and registerConnectorTools. Keep tool methods narrow and describe all limitations.
5. Add an enablement variable to AppConfig and loadConfiguration, then register the factory in connector-registration.ts.
6. Test the class directly with fake OAuthClient, TokenStore, logger, clock, and tool registrar dependencies. Do not test against a real provider in unit tests.

The included ExampleConnector follows this pattern and is covered by independent tests. It must not be copied as a real credential or token-storage implementation: InMemoryTokenStore and ExampleOAuthClient are demonstration-only.

Production characteristics

• Exact MCP SDK version is pinned (@modelcontextprotocol/sdk 1.30.0) for repeatable installs.
• Startup configuration is validated before serving requests.
• Structured JSON logging goes to stderr.
• Signal handling closes MCP and health resources cleanly.
• Docker runs as an unprivileged user with a read-only filesystem and a Docker health check.
• The image uses a multi-stage production build with development dependencies omitted.

Extending safely

1. Follow the connector-framework process above.
2. Add only the supported OAuth authentication flow; never log tokens or authorization headers.
3. Register the connector factory in src/connectors/connector-registration.ts.
4. Add narrow MCP tools through registerConnectorTools, with clear descriptions and appropriate annotations.
5. Add configuration validation, tests, and documentation for the capability and any provider approval requirement.