This server is a middleware that enables large language models (like Claude and VS Code) to interact directly with PlayFab services. Acting as a secure and efficient translator, it connects your AI assistant with various PlayFab functionalities, such as item search, segment inquiries, player profile lookups, inventory management, and PlayFab ID conversion.
PlayFab MCP server with CI/CD and release-please
ดาว
3
เครื่องมือ
—
อัปไทม์
—
Quick Example
You: "Show me the latest 10 items."
Claude: *calls the PlayFab search_items API and returns the results in plain text*
How Does It Work? 🛠️
This server leverages the Model Context Protocol (MCP) to establish a universal interface between AI models and PlayFab services. Although MCP is designed to support any AI model, it is currently available as a developer preview.
Follow these steps to get started:
Set up your project.
Add your project details to your LLM client's configuration.
Start interacting with PlayFab data naturally!
What Can It Do? 📊
Catalog & Search
Search for items using PlayFab's search_items API.
Catalog Management (Economy v2):
Create new draft items with the create_draft_item API.
Update existing draft items with the update_draft_item API.
Delete items from catalog with the delete_item API.
Publish draft items to make them available with the publish_draft_item API.
Get detailed item information with the get_item API.
Player Management
Retrieve comprehensive segment information.
Query player profiles within specified segments.
Convert a PlayFab ID to a Title Player Account ID via the get_title_player_account_id_from_playfab_id API.
Get detailed user account information with the get_user_account_info API.
Inventory Management
Get Operations:
Retrieve current inventory items with the get_inventory_items API.
Fetch inventory collection IDs using the get_inventory_collection_ids API.
Add/Remove Operations:
Add items to inventory with the add_inventory_items API.
Delete items from inventory with the delete_inventory_items API.
Subtract specific amounts with the subtract_inventory_items API.
Modify Operations:
Update item properties with the update_inventory_items API.
Economy v2 Administration
Execute batch inventory operations with the execute_inventory_operations API.
Note: In Economy v2, virtual currencies are managed as inventory items.
User Account Administration
Ban players by ID, IP, or MAC address with the ban_users API.
Unban players completely with the revoke_all_bans_for_user API.
Player Data Management
Retrieve player custom data with the get_user_data API.
Update player custom data with the update_user_data API.
Title Configuration Management
Set global title data with the set_title_data API.
Retrieve title data with the get_title_data API.
Set server-only internal data with the set_title_internal_data API.
Retrieve internal data with the get_title_internal_data API.
Quick Start 🚀
Prerequisites
Node.js 18 or higher.
A valid PlayFab account (obtain your Title ID and Developer Secret Key via PlayFab Game Manager).
A supported LLM client such as Claude Desktop.
Set Up Your Project
Obtain your PlayFab Title ID and Developer Secret Key from the PlayFab Game Manager, then create a .env file in the project root with the following content (replace the placeholders with your actual credentials):
PLAYFAB_TITLE_ID=
PLAYFAB_DEV_SECRET_KEY=
Installation and Setup
Install Dependencies
In the project root, run the following command to install all necessary dependencies:
npm install
Build the Project
Compile the project by executing:
npm run build
Start the Server
Start the server by executing:
npm start
Confirmation Message
Upon startup, you should see this message:
PlayFab Server running on stdio
Development Setup
Code Quality Tools
ESLint: Configured for TypeScript with recommended rules for code consistency
Prettier: Automatic code formatting with project-specific settings
TypeScript: Strict mode enabled for enhanced type safety
Jest: Testing framework configured for TypeScript
Available Scripts
# Build the project
npm run build
# Development mode with file watching
npm run watch
# TypeScript type checking
npm run typecheck
# Run ESLint
npm run lint
# Run ESLint and fix issues
npm run lint:fix
# Format code with Prettier
npm run format
# Check code formatting
npm run format:check
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
TypeScript Configuration
This project uses TypeScript with strict mode enabled, ensuring:
Strict null checks
No implicit any types
Strict function types
Always strict mode
Testing
Tests are written using Jest and can be found in __tests__ directories or files with .test.ts extension. Run tests before committing changes to ensure code quality.
The repository ships with a lightweight dev container (Node 22, tooling, GitHub CLI).
# Build image
docker compose build
# Open a shell inside the container
docker compose run --rm playfab-mcp-server bash
# Inside the container
npm ci
npm run build
npm start
Volumes keep your workspace (.), Codex/Claude configs, and shell history. Set PLAYFAB_TITLE_ID / PLAYFAB_DEV_SECRET_KEY in the container env when running the server.
Running with Cursor
To use the PlayFab MCP server with Cursor, follow these steps:
Copy the mcp.json file from this repository into your folder and update the values according to your environment.
Launch Cursor; the PlayFab MCP Server should appear in the tools list.
For example, try a prompt like "Show me the latest 10 items" to verify that the server processes your query correctly.
Adding Your Project Details to Claude Desktop's Config File
Open Claude Desktop and navigate to File → Settings → Developer → Edit Config. Then, replace the claude_desktop_config file content with the following snippet:
With these steps, you have successfully configured the PlayFab MCP server for use with your LLM client, allowing seamless interaction with PlayFab's services.
Spec-Driven Development with Spec Kit
This repository follows the Spec Kit SDD/TDD workflow used in akiojin/gwt.
style: Changes that do not affect the meaning of the code
refactor: A code change that neither fixes a bug nor adds a feature
perf: A code change that improves performance
test: Adding missing tests or correcting existing tests
chore: Changes to the build process or auxiliary tools
Version Bumping Rules
MAJOR version: When commit message contains BREAKING CHANGE in footer or ! after type/scope
Example: feat!: remove deprecated API endpoints
Example: feat: new API\n\nBREAKING CHANGE: removed old endpoints
MINOR version: When commit type is feat
Example: feat: add new PlayFab API integration
PATCH version: When commit type is fix
Example: fix: correct error handling in API calls
Release Process (develop → main, release-please)
Prepare release PR: Run the prepare-release.yml workflow to open a PR from develop to main
Actions UI: Prepare Release → run with ref develop
CLI: gh workflow run prepare-release.yml --ref develop
If a PR from develop already exists, it will be reused; PRs opened from develop can be auto-merged by the workflow.
Release automation: When main is updated, release.yml runs release-please (manifest) to bump versions, update CHANGELOG.md, and create the GitHub Release/tag.
Publish: Tag push v* triggers publish.yml to run tests, build, typecheck, and npm publish --access public.
Required secrets:
PERSONAL_ACCESS_TOKEN (optional; used by prepare-release/release when provided, falls back to GITHUB_TOKEN)
NPM_TOKEN (for publish.yml)
Branch protection: keep protections on main; release PRs should satisfy required checks before merge.
Scripts Reference
Script
Description
npm start
Start the MCP server
npm run build
Build TypeScript to JavaScript
npm run watch
Build in watch mode for development
npm run typecheck
Run TypeScript type checking
npm run lint
Run ESLint checks
npm run lint:fix
Fix ESLint issues automatically
npm run format
Format code with Prettier
npm run format:check
Check code formatting
npm test
Run all tests
npm run test:watch
Run tests in watch mode
npm run test:coverage
Generate test coverage report
Security
We take security seriously. If you discover a security vulnerability within this project, please follow these steps:
Reporting Security Vulnerabilities
DO NOT create a public GitHub issue for security vulnerabilities
Instead, please report security issues via GitHub's private vulnerability reporting:
Go to the Security tab of this repository
Click on Report a vulnerability
Provide detailed information about the vulnerability
What We Need From You
A description of the vulnerability
Steps to reproduce the issue
Potential impact
Any suggested fixes (optional)
Our Commitment
We will acknowledge receipt of your report within 48 hours
We will provide regular updates on our progress
We will credit you for the discovery (unless you prefer to remain anonymous)
Security Best Practices
When using this server:
Never commit credentials: Always use environment variables for sensitive data
Keep dependencies updated: Regularly run npm audit and update packages
Use least privilege: Only grant the minimum required permissions
Rotate keys regularly: Change your PlayFab Developer Secret Keys periodically
Support
Getting Help
If you encounter any issues or have questions about using the PlayFab MCP Server, here are the best ways to get support:
GitHub Issues: For bug reports and feature requests, please create an issue
Discussions: For general questions and community support, use GitHub Discussions
Documentation: Check the README and code comments for usage examples
Before Creating an Issue
Please check if your issue has already been reported by searching existing issues. If you find a similar issue, you can add additional information as a comment.