# JSONPlaceholder MCP Server

An MCP (Model Context Protocol) server that provides tools to interact with the JSONPlaceholder API - a free fake REST API for testing and prototyping.

## Features

This MCP server exposes the following tools:

### Tools

1. **get_posts** - Retrieve posts from JSONPlaceholder
   - Get all posts
   - Get a specific post by ID
   - Filter posts by user ID

2. **get_users** - Retrieve user information
   - Get all users
   - Get a specific user by ID

3. **get_comments** - Retrieve comments
   - Get all comments
   - Get a specific comment by ID
   - Get comments for a specific post

4. **get_todos** - Retrieve todos
   - Get all todos
   - Get a specific todo by ID
   - Filter todos by user ID

5. **create_post** - Create a new post (simulated)
   - Requires: userId, title, body

6. **update_post** - Update an existing post (simulated)
   - Requires: id
   - Optional: userId, title, body

7. **delete_post** - Delete a post (simulated)
   - Requires: id

### Resources

- **jsonplaceholder://api-info** - Information about the JSONPlaceholder API

## Installation

1. Clone this repository:
```bash
git clone <repository-url>
cd jsonplaceholder-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Usage

### Running the Server

```bash
npm start
```

### Development Mode

```bash
npm run dev
```

### Watch Mode (for development)

```bash
npm run watch
```

## Integration with Claude Desktop

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:

### macOS
Edit: `~/Library/Application Support/Claude/claude_desktop_config.json`

### Windows
Edit: `%APPDATA%/Claude/claude_desktop_config.json`

### Linux
Edit: `~/.config/Claude/claude_desktop_config.json`

Add this configuration:

```json
{
  "mcpServers": {
    "jsonplaceholder": {
      "command": "node",
      "args": ["/absolute/path/to/jsonplaceholder-mcp/dist/index.js"]
    }
  }
}
```

Replace `/absolute/path/to/jsonplaceholder-mcp` with the actual path to your installation.

## Example Usage in Claude

Once connected, you can ask Claude to:

- "Get all posts from JSONPlaceholder"
- "Show me user with ID 1"
- "Get comments for post 1"
- "Create a new post with title 'Test Post' and body 'This is a test'"
- "Get all todos for user 1"
- "Update post 1 with a new title"
- "Delete post 1"

## About JSONPlaceholder

JSONPlaceholder is a free fake REST API for testing and prototyping. It provides:
- 100 posts
- 500 comments
- 100 albums
- 5000 photos
- 200 todos
- 10 users

Note: All POST, PUT, PATCH, and DELETE operations are simulated and won't persist to the actual server.

API Base URL: https://jsonplaceholder.typicode.com

## Development

This project uses:
- **TypeScript** for type safety
- **@modelcontextprotocol/sdk** - Official Anthropic MCP SDK
- **Node.js** runtime

## Project Structure

```
jsonplaceholder-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.