Parse.ly MCP Server

A Model Context Protocol (MCP) server that provides access to Parse.ly analytics API. 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 CLAUDE.md for development guidance.

Features

• Dual Transport: Supports both stdio (for npx usage) and Streamable HTTP transport
• 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

Quick Start with npx

The easiest way to use this server is via npx. Add it to your MCP client configuration:

{
  "mcpServers": {
    "parsely": {
      "command": "npx",
      "args": ["parsely-mcp"],
      "env": {
        "PARSELY_API_KEY": "your_api_key_here",
        "PARSELY_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

This uses stdio transport, which is the default and works with Claude Desktop, Claude Code, and other MCP clients.

Local Development

1. Clone the repository:

git clone https://github.com/dailybeast/parsely-mcp.git
cd parsely-mcp

2. Install dependencies:

npm install

3. Create a .env file from the example:

cp .env.example .env

4. Edit .env and add your Parse.ly credentials:

PARSELY_API_KEY=your_api_key_here
PARSELY_API_SECRET=your_api_secret_here
PORT=8742

5. Build the project:

npm run build

6. Run the server:

# Stdio transport (default)
npm start

# HTTP transport
node dist/index.js --http

When using --http, the server starts on http://localhost:8742 with:

• MCP endpoint: http://localhost:8742/mcp - Streamable HTTP transport (POST, GET, DELETE)
• Health check: http://localhost:8742/health - Server health status

Docker

1. Build the Docker image:

docker build -t parsely-mcp .

2. Run the container with environment variables:

docker run -e PARSELY_API_KEY=your_key -e PARSELY_API_SECRET=your_secret -p 8742:8742 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:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PARSELY_API_KEY | Yes | - | Your Parse.ly API key | | PARSELY_API_SECRET | Yes | - | Your Parse.ly API secret | | PARSELY_API_BASE_URL | No | https://api.parse.ly/v2 | Parse.ly API base URL | | PORT | No | 8742 | Server port (HTTP mode only) |

API Documentation

For more information about the Parse.ly API:

• API Overview
• API Endpoints

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 LICENSE for details

Support

For issues and questions:

• GitHub Issues: https://github.com/dailybeast/parsely-mcp/issues
• Parse.ly Documentation: https://docs.parse.ly/

Acknowledgments

• Built with Claude Code - AI-assisted development
• Model Context Protocol SDK - TypeScript SDK for MCP
• Parse.ly API - Content analytics platform

Development

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

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