README.md•5.65 kB
# Fake Store API MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that provides seamless access to the [Fake Store API](https://fakestoreapi.com) for AI assistants. Perfect for e-commerce demos, testing, and learning MCP development.
## Features
- 🛍️ **Complete E-commerce Data Access**: Products, carts, and users
- 🔧 **18 MCP Tools**: Full CRUD operations for all resources
- 📦 **Easy Integration**: Works with Claude Desktop, Plugged.in, and other MCP clients
- 🚀 **Zero Configuration**: Works out of the box with Fake Store API
- 📝 **TypeScript**: Fully typed for better development experience
- ✅ **Input Validation**: Comprehensive parameter validation
## Installation
### NPX (Recommended)
```bash
npx -y mcp-server-fakestore
```
### From Source
```bash
git clone https://github.com/yourusername/mcp-server-fakestore.git
cd mcp-server-fakestore
npm install
npm run build
```
## Configuration
### Claude Desktop
Add this to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"fakestore": {
"command": "npx",
"args": ["-y", "mcp-server-fakestore"]
}
}
}
```
### Plugged.in
Add this server configuration in Plugged.in MCP settings:
```json
{
"name": "fakestore",
"command": "npx",
"args": ["-y", "mcp-server-fakestore"]
}
```
## Available Tools
### Products (7 tools)
- `fakestore_get_products` - Get all products with optional limit and sorting
- `fakestore_get_product` - Get a single product by ID
- `fakestore_get_categories` - Get all product categories
- `fakestore_get_products_by_category` - Get products in a specific category
- `fakestore_add_product` - Add a new product (simulation)
- `fakestore_update_product` - Update an existing product (simulation)
- `fakestore_delete_product` - Delete a product (simulation)
### Carts (6 tools)
- `fakestore_get_carts` - Get all carts with optional limit and sorting
- `fakestore_get_cart` - Get a single cart by ID
- `fakestore_get_user_carts` - Get all carts for a specific user
- `fakestore_add_cart` - Add a new cart (simulation)
- `fakestore_update_cart` - Update an existing cart (simulation)
- `fakestore_delete_cart` - Delete a cart (simulation)
### Users (5 tools)
- `fakestore_get_users` - Get all users with optional limit and sorting
- `fakestore_get_user` - Get a single user by ID
- `fakestore_add_user` - Add a new user (simulation)
- `fakestore_update_user` - Update an existing user (simulation)
- `fakestore_delete_user` - Delete a user (simulation)
## Usage Examples
### With Claude Desktop
**Get all products:**
```
Show me all products from the fake store
```
**Search by category:**
```
Show me electronics from the fake store
```
**Get user's cart:**
```
What's in user ID 1's shopping cart?
```
**Product analysis:**
```
Find the 5 most expensive products in the store
```
### Programmatic Usage
```typescript
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
// The server runs on stdio transport
// Connect your MCP client to interact with the tools
```
## Data Structure
### Product
```typescript
{
id: number;
title: string;
price: number;
description: string;
category: string;
image: string;
rating: {
rate: number;
count: number;
};
}
```
### Cart
```typescript
{
id: number;
userId: number;
date: string;
products: Array<{
productId: number;
quantity: number;
}>;
}
```
### User
```typescript
{
id: number;
email: string;
username: string;
password: string;
name: {
firstname: string;
lastname: string;
};
address: {
city: string;
street: string;
number: number;
zipcode: string;
geolocation: {
lat: string;
long: string;
};
};
phone: string;
}
```
## Development
```bash
# Install dependencies
npm install
# Build the project
npm run build
# Watch mode for development
npm run watch
# Run tests
npm test
```
## Important Notes
- **Simulation**: The Fake Store API is read-only. POST, PUT, and DELETE operations return simulated responses but don't persist data.
- **Rate Limits**: The public API has no strict rate limits, but please be respectful.
- **Data**: All data is fake and for testing purposes only.
## Troubleshooting
### Server not appearing in Claude Desktop
1. Ensure the configuration file is valid JSON
2. Restart Claude Desktop completely
3. Check the Claude Desktop logs for errors
### Tools not working
1. Verify you have an active internet connection (API requires connectivity)
2. Check if fakestoreapi.com is accessible
3. Review error messages in Claude Desktop logs
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Resources
- [Fake Store API Documentation](https://fakestoreapi.com/docs)
- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
## Support
- 🐛 [Report Issues](https://github.com/yourusername/mcp-server-fakestore/issues)
- 💬 [Discussions](https://github.com/yourusername/mcp-server-fakestore/discussions)
- 📧 Email: your.email@example.com
---
Built with ❤️ for the MCP community