# JSONPlaceholder MCP Server
A modern Model Context Protocol (MCP) server built with FastMCP that provides access to the JSONPlaceholder API - a free fake REST API for testing and prototyping.
## Features
This MCP server provides **Resources**, **Tools**, and **Prompts** for interacting with JSONPlaceholder:
### 🔧 **Tools** (Actions)
- **get_posts** - Retrieve all posts or a specific post by ID
- **get_users** - Retrieve all users or a specific user by ID
- **get_comments** - Retrieve comments, optionally filtered by post ID
- **get_albums** - Retrieve albums, optionally filtered by user ID
- **get_photos** - Retrieve photos, optionally filtered by album ID
- **get_todos** - Retrieve todos, optionally filtered by user ID
- **create_post** - Create a new post (simulated)
- **search_posts** - Search posts by title or body content
### 📄 **Resources** (Data Access)
- **posts://all** - Get all posts as a resource
- **posts://{post_id}** - Get a specific post as a resource
- **users://all** - Get all users as a resource
- **users://{user_id}** - Get a specific user as a resource
### 📝 **Prompts** (Templates)
- **analyze_post** - Generate analysis prompt for a specific post
- **user_profile_summary** - Create comprehensive user profile analysis
### How to add it to cursor:
```bash {
"mcpServers": {
"jsonplaceholder": {
"command": "/Users/danielpopa/Projects/work/mcp-server/cursor_runner.sh",
"args": []
}
}
}
```
### Prerequisites
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager
### Installation
1. Clone or download this project
2. The project is already configured with uv. Simply run:
```bash
uv sync
```
### Development & Testing
**MCP Inspector** (recommended for development):
```bash
uv run mcp dev server.py
```
This opens an interactive web interface to test all tools, resources, and prompts.
**Direct server execution**:
```bash
uv run python server.py
```
**Test API connectivity**:
```bash
uv run python test_server.py
```
### Claude Desktop Integration
Install directly into Claude Desktop:
```bash
uv run mcp install server.py --name "JSONPlaceholder API"
```
### Usage Examples
Once connected to an MCP client, you can:
**Use Tools:**
- "Get all posts from JSONPlaceholder"
- "Show me user details for user ID 1"
- "Search for posts containing 'dolor'"
- "Create a new post titled 'Test' with body 'Hello World' for user 1"
**Access Resources:**
- The client can load `posts://all` to get all posts as context
- Load `users://5` to get user 5's details as background information
**Use Prompts:**
- Use the "analyze_post" prompt with post ID 1 for detailed post analysis
- Use "user_profile_summary" with user ID 2 for comprehensive user profiling
## API Information
This server uses the JSONPlaceholder API (https://jsonplaceholder.typicode.com/), which provides:
- 100 posts
- 10 users
- 500 comments
- 100 albums
- 5000 photos
- 200 todos
No API key is required as it's completely free and public.
## Architecture
Built with **FastMCP**, this server demonstrates modern MCP patterns:
- **Decorator-based setup** - Clean, Pythonic code
- **Type hints** - Better development experience
- **Async/await** - Efficient HTTP requests
- **Resource management** - Proper data exposure to LLMs
- **Prompt templates** - Reusable interaction patterns
- **Development tools** - Built-in testing and debugging
## Development
The server uses:
- **FastMCP** - Modern MCP server framework
- **httpx** - Async HTTP client
- **Python 3.10+** - Modern Python features
- **uv** - Fast Python package management
