parsely-mcp

dailybeast/parsely-mcp

3.2

If you are the rightful owner of parsely-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Parse.ly MCP Server is a Model Context Protocol server that provides access to the Parse.ly analytics API, enabling AI assistants to query data for content analytics, referrers, search, and social shares.

Tools
6
Resources
0
Prompts
0

Parse.ly MCP Server

A Model Context Protocol (MCP) server that provides access to Parse.ly analytics API via streaming HTTP with Server-Sent Events (SSE). This server enables AI assistants like Claude to query Parse.ly data for content analytics, referrers, search, and social shares.

Built with Claude Code - See for development guidance.

Features

  • Streaming HTTP Transport: Server-Sent Events (SSE) for real-time MCP communication
  • Analytics Tools: Get metrics for top posts, authors, and tags with date-based queries
  • Referrer Data: Track traffic sources by type (social, search, other, internal)
  • Content Search: Search through Parse.ly content
  • Social Shares: View share counts across platforms
  • Date Range Support: Query specific days or ranges for time-based comparisons
  • Type-Safe: Built with TypeScript for reliability
  • Well-Tested: Comprehensive unit tests with mocked API responses
  • Docker Support: Easy containerized deployment with port exposure

Prerequisites

  • Node.js >= 20.0.0
  • Parse.ly API credentials (API key and secret)
  • Get your credentials from https://dash.parse.ly/

Installation

Local Development

  1. Clone the repository:
git clone https://github.com/dailybeast/parsely-mcp.git
cd parsely-mcp
  1. Install dependencies:
npm install
  1. Create a .env file from the example:
cp .env.example .env
  1. Edit .env and add your Parse.ly credentials:
PARSELY_API_KEY=your_api_key_here
PARSELY_API_SECRET=your_api_secret_here
PORT=3000
  1. Build the project:
npm run build
  1. Run the server:
npm start

The server will start on http://localhost:3000 with the following endpoints:

  • SSE endpoint: http://localhost:3000/sse - MCP Server-Sent Events transport
  • Health check: http://localhost:3000/health - Server health status

Docker

  1. Build the Docker image:
docker build -t parsely-mcp .
  1. Run the container with environment variables:
docker run -e PARSELY_API_KEY=your_key -e PARSELY_API_SECRET=your_secret -p 3000:3000 parsely-mcp

Available Tools

The MCP server exposes the following tools:

get_analytics_posts

Get analytics data for top posts.

  • Parameters: days (number, default: 7), limit (number, default: 10), sort (string, optional)

get_analytics_authors

Get analytics data for top authors.

  • Parameters: days (number, default: 7), limit (number, default: 10)

get_analytics_tags

Get analytics data for top tags.

  • Parameters: days (number, default: 7), limit (number, default: 10)

get_referrers

Get referrer data showing traffic sources.

  • Parameters: days (number, default: 7), limit (number, default: 10), type (string, optional: "social", "search", etc.)

search_content

Search Parse.ly content.

  • Parameters: query (string, required), limit (number, default: 10)

get_shares

Get social share data for posts.

  • Parameters: days (number, default: 7), limit (number, default: 10)

Development

Available Scripts

npm run build          # Compile TypeScript
npm run dev            # Watch mode for development
npm run lint           # Run ESLint
npm test               # Run tests
npm run test:watch     # Run tests in watch mode
npm run test:coverage  # Generate coverage report

Running Tests

Tests use mocked Parse.ly API responses and don't require real credentials:

npm test

For tests that need environment variables:

PARSELY_API_KEY=test PARSELY_API_SECRET=test npm test

Configuration

All configuration is done via environment variables:

VariableRequiredDefaultDescription
PARSELY_API_KEYYes-Your Parse.ly API key
PARSELY_API_SECRETYes-Your Parse.ly API secret
PARSELY_API_BASE_URLNohttps://api.parse.ly/v2Parse.ly API base URL
PORTNo3000Server port

API Documentation

For more information about the Parse.ly API:

Contributing

Contributions are welcome! Please ensure:

  1. All tests pass (npm test)
  2. Code is linted (npm run lint)
  3. TypeScript compiles without errors (npm run build)

License

MIT License - see for details

Support

For issues and questions:

Acknowledgments

Development

This project uses for AI-assisted development guidance. The file contains:

  • Architecture overview and code organization
  • Common development commands
  • Testing requirements and conventions
  • Open-source best practices